cmdx 1.10.0 → 1.10.1

data/docs/getting_started.md

@@ -2,10 +2,10 @@
 
 CMDx is a Ruby framework for building maintainable, observable business logic through composable command objects. It brings structure, consistency, and powerful developer tools to your business processes.
 
-**Common challenges it solves:**
+**Common challenges:**
 
 - Inconsistent service object patterns across your codebase
-- Limited logging makes debugging a nightmare
+- Black boxes make debugging a nightmare
 - Fragile error handling erodes confidence
 
 **What you get:**
@@ -17,343 +17,80 @@ CMDx is a Ruby framework for building maintainable, observable business logic th
 - Attribute validation with type coercions
 - Sensible defaults and developer-friendly APIs
 
-## The CERO Pattern
-
-CMDx embraces the Compose, Execute, React, Observe (CERO) pattern—a simple yet powerful approach to building reliable business logic.
-
-🧩 **Compose** — Define small, focused tasks with typed attributes and validations
-
-⚡ **Execute** — Run tasks with clear outcomes and pluggable behaviors
-
-🔄 **React** — Adapt to outcomes by chaining follow-up tasks or handling faults
-
-🔍 **Observe** — Capture structured logs and execution chains for debugging
-
 ## Installation
 
 Add CMDx to your Gemfile:
 
-```ruby
-gem 'cmdx'
-```
+```sh
+gem install cmdx
 
-For Rails applications, generate the configuration:
+# - or -
 
-```bash
-rails generate cmdx:install
+bundle add cmdx
 ```
 
-This creates `config/initializers/cmdx.rb` file.
-
-## 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
-```
+## Configuration
 
-### Rollback
+For Rails applications, run the following command to generate a global configuration file in `config/initializers/cmdx.rb`.
 
-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
+```bash
+rails generate cmdx:install
 ```
 
-### 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
+If not using Rails, manually copy the [configuration file](https://github.com/drexed/cmdx/blob/main/lib/generators/cmdx/templates/install.rb).
 
-  # 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
-```
+## The CERO Pattern
 
-## Task Configuration
+CMDx embraces the Compose, Execute, React, Observe (CERO, pronounced "zero") pattern—a simple yet powerful approach to building reliable business logic.
 
-### Settings
+### Compose
 
-Override global configuration for specific tasks using `settings`:
+Build reusable, single-responsibility tasks with typed attributes, validation, and callbacks. Tasks can be chained together in workflows to create complex business processes from simple building blocks.
 
 ```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
-  )
-
+class AnalyzeMetrics < CMDx::Task
   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.
+### Execute
 
-### Registrations
-
-Register or deregister middlewares, callbacks, coercions, and validators for specific tasks:
+Invoke tasks with a consistent API that always returns a result object. Execution automatically handles validation, type coercion, error handling, and logging. Arguments are validated and coerced before your task logic runs.
 
 ```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
+# Without args
+result = AnalyzeMetrics.execute
 
-  def work
-    # Your logic here...
-  end
-end
+# With args
+result = AnalyzeMetrics.execute(model: "blackbox", "sensitivity" => 3)
 ```
 
-## Configuration Management
+### React
 
-### Access
+Every execution returns a result object with a clear outcome. Check the result's state (`success?`, `failed?`, `skipped?`) and access returned values, error messages, and metadata to make informed decisions.
 
 ```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
+if result.success?
+  # Handle success
+elsif result.skipped?
+  # Handle skipped
+elsif result.failed?
+  # Handle failed
 end
 ```
 
-### Resetting
+### Observe
 
-!!! warning
+Every task execution generates structured logs with execution chains, runtime metrics, and contextual metadata. Logs can be automatically correlated using chain IDs, making it easy to trace complex workflows and debug issues.
 
-    Resetting affects your entire application. Use this primarily in test environments.
-
-```ruby
-# Reset to framework defaults
-CMDx.reset_configuration!
+```log
+I, [2022-07-17T18:42:37.000000 #3784] INFO -- CMDx:
+index=1 chain_id="018c2b95-23j4-2kj3-32kj-3n4jk3n4jknf" type="Task" class="SendAnalyzedEmail" state="complete" status="success" metadata={runtime: 347}
 
-# 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
+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}
 ```
 
 ## Task Generator

data/docs/index.md

@@ -8,7 +8,7 @@ Build business logic that's powerful, predictable, and maintainable.
 
 ---
 
-Say goodbye to messy service objects. CMDx helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
+Say goodbye to messy service objects. CMDx (pronounced "Command X") helps you design business logic with clarity and consistency—build faster, debug easier, and ship with confidence.
 
 !!! note
 
@@ -24,7 +24,9 @@ CMDx works with any Ruby framework. Rails support is built-in, but it's framewor
 
 ```sh
 gem install cmdx
+
 # - or -
+
 bundle add cmdx
 ```
 
@@ -125,7 +127,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](https://github.com/drexed/cmdx/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 

data/docs/retries.md

@@ -17,7 +17,7 @@ class FetchExternalData < CMDx::Task
 end
 ```
 
-When an exception occurs during execution, CMDx automatically retries up to the configured limit.
+When an exception occurs during execution, CMDx automatically retries up to the configured limit. Each retry attempt is logged at the `warn` level with retry metadata. If all retries are exhausted, the task fails with the original exception.
 
 ## Selective Retries
 

data/docs/stylesheets/extra.css

@@ -9,34 +9,34 @@
   --md-accent-fg-color--transparent:   hsla(#{hex2hsl(#fe1817)}, 0.1);
 }
 
-/* Atom One Light Pro syntax highlighting */
+/* GitHub High Contrast Light syntax highlighting */
 [data-md-color-scheme="default"] {
-  --md-code-hl-color:            #2c3036;
-  --md-code-hl-keyword-color:    #a626a4;
-  --md-code-hl-string-color:     #50a14f;
-  --md-code-hl-name-color:       #e4564a;
-  --md-code-hl-function-color:   #4078f2;
-  --md-code-hl-number-color:     #ca7601;
-  --md-code-hl-constant-color:   #c18401;
-  --md-code-hl-comment-color:    #9ca0a4;
-  --md-code-hl-operator-color:   #0184bc;
-  --md-code-hl-punctuation-color:#383a42;
-  --md-code-hl-variable-color:   #e4564a;
-  --md-code-hl-generic-color:    #e4564a;
+  --md-code-hl-color:            #0e1116;
+  --md-code-hl-keyword-color:    #a0095d;
+  --md-code-hl-string-color:     #024c1a;
+  --md-code-hl-name-color:       #622cbc;
+  --md-code-hl-function-color:   #622cbc;
+  --md-code-hl-number-color:     #0349b4;
+  --md-code-hl-constant-color:   #702c00;
+  --md-code-hl-comment-color:    #66707b;
+  --md-code-hl-operator-color:   #a0095d;
+  --md-code-hl-punctuation-color:#0e1116;
+  --md-code-hl-variable-color:   #702c00;
+  --md-code-hl-generic-color:    #622cbc;
 }
 
-/* Atom One Dark Pro syntax highlighting */
+/* GitHub High Contrast Dark syntax highlighting */
 [data-md-color-scheme="slate"] {
-  --md-code-hl-color:            #e5e5e6;
-  --md-code-hl-keyword-color:    #c678dd;
-  --md-code-hl-string-color:     #98c379;
-  --md-code-hl-name-color:       #e06c75;
-  --md-code-hl-function-color:   #61afef;
-  --md-code-hl-number-color:     #d19a66;
-  --md-code-hl-constant-color:   #d19a66;
-  --md-code-hl-comment-color:    #7f848e;
-  --md-code-hl-operator-color:   #56b6c2;
-  --md-code-hl-punctuation-color:#abb2bf;
-  --md-code-hl-variable-color:   #e06c75;
-  --md-code-hl-generic-color:    #e06c75;
+  --md-code-hl-color:            #f0f3f6;
+  --md-code-hl-keyword-color:    #ff9492;
+  --md-code-hl-string-color:     #addcff;
+  --md-code-hl-name-color:       #dbb7ff;
+  --md-code-hl-function-color:   #dbb7ff;
+  --md-code-hl-number-color:     #91cbff;
+  --md-code-hl-constant-color:   #ffb757;
+  --md-code-hl-comment-color:    #9ea7b3;
+  --md-code-hl-operator-color:   #ff9492;
+  --md-code-hl-punctuation-color:#f0f3f6;
+  --md-code-hl-variable-color:   #ffb757;
+  --md-code-hl-generic-color:    #dbb7ff;
 }

data/docs/tips_and_tricks.md

@@ -145,8 +145,9 @@ class ConfigureCompany < CMDx::Task
 end
 ```
 
-## More Examples
+## Useful 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)
+- [Sidekiq Async Execution](https://github.com/drexed/cmdx/blob/main/examples/sidekiq_async_execution.md)
 - [Stoplight Circuit Breaker](https://github.com/drexed/cmdx/blob/main/examples/stoplight_circuit_breaker.md)

data/examples/sidekiq_async_execution.md

@@ -0,0 +1,29 @@
+# Sidekiq Async Execute
+
+Execute tasks asynchronously using Sidekiq without creating separate job classes.
+
+<https://github.com/sidekiq/sidekiq>
+
+### Setup
+
+```ruby
+class MyTask < CMDx::Task
+  include Sidekiq::Job
+
+  def work
+    # Do work...
+  end
+
+  # Use execute! to trigger Sidekiq's retry logic on failures/exceptions.
+  def perform
+    self.class.execute!
+  end
+
+end
+```
+
+### Usage
+
+```ruby
+MyTask.perform_async
+```

data/lib/cmdx/executor.rb

@@ -197,13 +197,6 @@ module CMDx
 
     private
 
-    # Lazy loaded repeator instance to handle retries.
-    #
-    # @rbs () -> untyped
-    def repeator
-      @repeator ||= Repeator.new(task)
-    end
-
     # Performs pre-execution tasks including validation and attribute verification.
     #
     # @rbs () -> void

data/lib/cmdx/version.rb

@@ -5,6 +5,6 @@ module CMDx
   # @return [String] the version of the CMDx gem
   #
   # @rbs return: String
-  VERSION = "1.10.0"
+  VERSION = "1.10.1"
 
 end