cmdx 1.12.0 → 1.14.0

data/docs/outcomes/result.md

@@ -1,194 +0,0 @@
-# Outcomes - Result
-
-Results are your window into task execution. They expose everything: outcome, state, timing, context, and metadata.
-
-## Result Attributes
-
-Access essential execution information:
-
-!!! warning "Important"
-
-    Results are immutable after execution completes.
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-# Object data
-result.task     #=> <BuildApplication>
-result.context  #=> <CMDx::Context>
-result.chain    #=> <CMDx::Chain>
-
-# Execution data
-result.state    #=> "interrupted"
-result.status   #=> "failed"
-
-# Fault data
-result.reason   #=> "Build tool not found"
-result.cause    #=> <CMDx::FailFault>
-result.metadata #=> { error_code: "BUILD_TOOL.NOT_FOUND" }
-```
-
-## Lifecycle Information
-
-Check execution state and status with predicate methods:
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-# State predicates (execution lifecycle)
-result.complete?    #=> true (successful completion)
-result.interrupted? #=> false (no interruption)
-result.executed?    #=> true (execution finished)
-
-# Status predicates (execution outcome)
-result.success?     #=> true (successful execution)
-result.failed?      #=> false (no failure)
-result.skipped?     #=> false (not skipped)
-
-# Outcome categorization
-result.good?        #=> true (success or skipped)
-result.bad?         #=> false (skipped or failed)
-```
-
-## Outcome Analysis
-
-Get a unified outcome string combining state and status:
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-result.outcome #=> "success" (state and status)
-```
-
-## Chain Analysis
-
-Trace fault origins and propagation:
-
-```ruby
-result = DeploymentWorkflow.execute(app_name: "webapp")
-
-if result.failed?
-  # Find the original cause of failure
-  if original_failure = result.caused_failure
-    puts "Root cause: #{original_failure.task.class.name}"
-    puts "Reason: #{original_failure.reason}"
-  end
-
-  # Find what threw the failure to this result
-  if throwing_task = result.threw_failure
-    puts "Failure source: #{throwing_task.task.class.name}"
-    puts "Reason: #{throwing_task.reason}"
-  end
-
-  # Failure classification
-  result.caused_failure?  #=> true if this result was the original cause
-  result.threw_failure?   #=> true if this result threw a failure
-  result.thrown_failure?  #=> true if this result received a thrown failure
-end
-```
-
-## Index and Position
-
-Results track their position within execution chains:
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-# Position in execution sequence
-result.index #=> 0 (first task in chain)
-
-# Access via chain
-result.chain.results[result.index] == result #=> true
-```
-
-## Block Yield
-
-Execute code with direct result access:
-
-```ruby
-BuildApplication.execute(version: "1.2.3") do |result|
-  if result.success?
-    notify_deployment_ready(result)
-  elsif result.failed?
-    handle_build_failure(result)
-  else
-    log_skip_reason(result)
-  end
-end
-```
-
-## Handlers
-
-Handle outcomes with functional-style methods. Handlers return the result for chaining:
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-# Status-based handlers
-result
-  .on(:success) { |result| notify_deployment_ready(result) }
-  .on(:failed) { |result| handle_build_failure(result) }
-  .on(:skipped) { |result| log_skip_reason(result) }
-
-# State-based handlers
-result
-  .on(:complete) { |result| update_build_status(result) }
-  .on(:interrupted) { |result| cleanup_partial_artifacts(result) }
-  .on(:executed) { |result| alert_operations_team(result) } #=> .on(:complete, :interrupted)
-
-# Outcome-based handlers
-result
-  .on(:good) { |result| increment_success_counter(result) } #=> .on(:success, :skipped)
-  .on(:bad) { |result| alert_operations_team(result) }      #=> .on(:failed, :skipped)
-```
-
-## Pattern Matching
-
-Use Ruby 3.0+ pattern matching for elegant outcome handling:
-
-!!! warning "Important"
-
-    Pattern matching works with both array and hash deconstruction.
-
-### Array Pattern
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-case result
-in ["complete", "success"]
-  redirect_to build_success_page
-in ["interrupted", "failed"]
-  retry_build_with_backoff(result)
-in ["interrupted", "skipped"]
-  log_skip_and_continue
-end
-```
-
-### Hash Pattern
-
-```ruby
-result = BuildApplication.execute(version: "1.2.3")
-
-case result
-in { state: "complete", status: "success" }
-  celebrate_build_success
-in { status: "failed", metadata: { retryable: true } }
-  schedule_build_retry(result)
-in { bad: true, metadata: { reason: String => reason } }
-  escalate_build_error("Build failed: #{reason}")
-end
-```
-
-### Pattern Guards
-
-```ruby
-case result
-in { status: "failed", metadata: { attempts: n } } if n < 3
-  retry_build_with_delay(result, n * 2)
-in { status: "failed", metadata: { attempts: n } } if n >= 3
-  mark_build_permanently_failed(result)
-in { runtime: time } if time > performance_threshold
-  investigate_build_performance(result)
-end
-```

data/docs/outcomes/states.md

@@ -1,66 +0,0 @@
-# Outcomes - States
-
-States track where a task is in its execution lifecycle—from creation through completion or interruption.
-
-## Definitions
-
-| State | Description |
-| ----- | ----------- |
-| `initialized` | Task created but execution not yet started. Default state for new tasks. |
-| `executing` | Task is actively running its business logic. Transient state during execution. |
-| `complete` | Task finished execution successfully without any interruption or halt. |
-| `interrupted` | Task execution was stopped due to a fault, exception, or explicit halt. |
-
-State-Status combinations:
-
-| State | Status | Meaning |
-| ----- | ------ | ------- |
-| `initialized` | `success` | Task created, not yet executed |
-| `executing` | `success` | Task currently running |
-| `complete` | `success` | Task finished successfully |
-| `complete` | `skipped` | Task finished by skipping execution |
-| `interrupted` | `failed` | Task stopped due to failure |
-| `interrupted` | `skipped` | Task stopped by skip condition |
-
-## Transitions
-
-!!! danger "Caution"
-
-    States are managed automatically—never modify them manually.
-
-```ruby
-# Valid state transition flow
-initialized → executing → complete    (successful execution)
-initialized → executing → interrupted (skipped/failed execution)
-```
-
-## Predicates
-
-Use state predicates to check the current execution lifecycle:
-
-```ruby
-result = ProcessVideoUpload.execute
-
-# Individual state checks
-result.initialized? #=> false (after execution)
-result.executing?   #=> false (after execution)
-result.complete?    #=> true (successful completion)
-result.interrupted? #=> false (no interruption)
-
-# State categorization
-result.executed?    #=> true (complete OR interrupted)
-```
-
-## Handlers
-
-Handle lifecycle events with state-based handlers. Use `on(:executed)` for cleanup that runs regardless of outcome:
-
-```ruby
-result = ProcessVideoUpload.execute
-
-# Individual state handlers
-result
-  .on(:complete) { |result| send_upload_notification(result) }
-  .on(:interrupted) { |result| cleanup_temp_files(result) }
-  .on(:executed) { |result| log_upload_metrics(result) } #=> .on(:complete, :interrupted)
-```

data/docs/outcomes/statuses.md

@@ -1,65 +0,0 @@
-# Outcomes - Statuses
-
-Statuses represent the business outcome—did the task succeed, skip, or fail? This differs from state, which tracks the execution lifecycle.
-
-## Definitions
-
-| Status | Description |
-| ------ | ----------- |
-| `success` | Task execution completed successfully with expected business outcome. Default status for all tasks. |
-| `skipped` | Task intentionally stopped execution because conditions weren't met or continuation was unnecessary. |
-| `failed` | Task stopped execution due to business rule violations, validation errors, or exceptions. |
-
-## Transitions
-
-!!! warning "Important"
-
-    Status transitions are final and unidirectional. Once skipped or failed, tasks can't return to success.
-
-```ruby
-# Valid status transitions
-success → skipped    # via skip!
-success → failed     # via fail! or exception
-
-# Invalid transitions (will raise errors)
-skipped → success    # ❌ Cannot transition
-skipped → failed     # ❌ Cannot transition
-failed → success     # ❌ Cannot transition
-failed → skipped     # ❌ Cannot transition
-```
-
-## Predicates
-
-Use status predicates to check execution outcomes:
-
-```ruby
-result = ProcessNotification.execute
-
-# Individual status checks
-result.success? #=> true/false
-result.skipped? #=> true/false
-result.failed?  #=> true/false
-
-# Outcome categorization
-result.good?    #=> true if success OR skipped
-result.bad?     #=> true if skipped OR failed (not success)
-```
-
-## Handlers
-
-Branch business logic with status-based handlers. Use `on(:good)` and `on(:bad)` for success/skip vs failed outcomes:
-
-```ruby
-result = ProcessNotification.execute
-
-# Individual status handlers
-result
-  .on(:success) { |result| mark_notification_sent(result) }
-  .on(:skipped) { |result| log_notification_skipped(result) }
-  .on(:failed){ |result| queue_retry_notification(result) }
-
-# Outcome-based handlers
-result
-  .on(:good) { |result| update_message_stats(result) }  #=> .on(:success, :skipped)
-  .on(:bad) { |result| track_delivery_failure(result) } #=> .on(:failed, :skipped)
-```

data/docs/retries.md

@@ -1,121 +0,0 @@
-# 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. 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
-
-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/stylesheets/extra.css

@@ -1,42 +0,0 @@
-:root  > * {
-  /* Primary color shades */
-  --md-primary-fg-color:        #fe1817;
-  --md-primary-fg-color--light: #fe1817;
-  --md-primary-fg-color--dark:  #fe1817;
-
-  /* Accent color shades */
-  --md-accent-fg-color:                hsla(#{hex2hsl(#fe1817)}, 1);
-  --md-accent-fg-color--transparent:   hsla(#{hex2hsl(#fe1817)}, 0.1);
-}
-
-/* GitHub High Contrast Light syntax highlighting */
-[data-md-color-scheme="default"] {
-  --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;
-}
-
-/* GitHub High Contrast Dark syntax highlighting */
-[data-md-color-scheme="slate"] {
-  --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

@@ -1,157 +0,0 @@
-# Tips and Tricks
-
-Best practices, patterns, and techniques to build maintainable CMDx applications.
-
-## Project Organization
-
-### Directory Structure
-
-Create a well-organized command structure for maintainable applications:
-
-```text
-/app/
-└── /tasks/
-    ├── /invoices/
-    │   ├── calculate_tax.rb
-    │   ├── validate_invoice.rb
-    │   ├── send_invoice.rb
-    │   └── process_invoice.rb # workflow
-    ├── /reports/
-    │   ├── generate_pdf.rb
-    │   ├── compile_data.rb
-    │   ├── export_csv.rb
-    │   └── create_reports.rb # workflow
-    ├── application_task.rb # base class
-    ├── authenticate_session.rb
-    └── activate_account.rb
-```
-
-### Naming Conventions
-
-Follow consistent naming patterns for clarity and maintainability:
-
-```ruby
-# Verb + Noun
-class ExportData < CMDx::Task; end
-class CompressFile < CMDx::Task; end
-class ValidateSchema < CMDx::Task; end
-
-# Use present tense verbs for actions
-class GenerateToken < CMDx::Task; end      # ✓ Good
-class GeneratingToken < CMDx::Task; end    # ❌ Avoid
-class TokenGeneration < CMDx::Task; end    # ❌ Avoid
-```
-
-### Story Telling
-
-Break down complex logic into descriptive methods that read like a narrative:
-
-```ruby
-class ProcessOrder < CMDx::Task
-  def work
-    charge_payment_method
-    assign_to_warehouse
-    send_notification
-  end
-
-  private
-
-  def charge_payment_method
-    order.primary_payment_method.charge!
-  end
-
-  def assign_to_warehouse
-    order.ready_for_shipping!
-  end
-
-  def send_notification
-    if order.products_out_of_stock?
-      OrderMailer.pending(order).deliver
-    else
-      OrderMailer.preparing(order).deliver
-    end
-  end
-end
-```
-
-### Style Guide
-
-Follow this order for consistent, readable tasks:
-
-```ruby
-class ExportReport < CMDx::Task
-
-  # 1. Register functions
-  register :middleware, CMDx::Middlewares::Correlate
-  register :validator, :format, FormatValidator
-
-  # 2. Define callbacks
-  before_execution :find_report
-  on_complete :track_export_metrics, if: ->(task) { Current.tenant.analytics? }
-
-  # 3. Declare attributes
-  attributes :user_id
-  required :report_id
-  optional :format_type
-
-  # 4. Define work method
-  def work
-    report.compile!
-    report.export!
-
-    context.exported_at = Time.now
-  end
-
-  # TIP: Favor private business logic to reduce the surface of the public API.
-  private
-
-  # 5. Build helper functions
-  def find_report
-    @report ||= Report.find(report_id)
-  end
-
-  def track_export_metrics
-    Analytics.increment(:report_exported)
-  end
-
-end
-```
-
-## Attribute Options
-
-Use `with_options` to reduce duplication:
-
-```ruby
-class ConfigureCompany < CMDx::Task
-  # Apply common options to multiple attributes
-  with_options(type: :string, presence: true) do
-    attributes :website, format: { with: URI::DEFAULT_PARSER.make_regexp(%w[http https]) }
-    required :company_name, :industry
-    optional :description, format: { with: /\A[\w\s\-\.,!?]+\z/ }
-  end
-
-  # Nested attributes with shared prefix
-  required :headquarters do
-    with_options(prefix: :hq_) do
-      attributes :street, :city, :zip_code, type: :string
-      required :country, type: :string, inclusion: { in: VALID_COUNTRIES }
-      optional :region, type: :string
-    end
-  end
-
-  def work
-    # Your logic here...
-  end
-end
-```
-
-## Useful Examples
-
-- [Active Record Database Transaction](https://github.com/drexed/cmdx/blob/main/examples/active_record_database_transaction.md)
-- [Active Record Query Tagging](https://github.com/drexed/cmdx/blob/main/examples/active_record_query_tagging.md)
-- [Flipper Feature Flags](https://github.com/drexed/cmdx/blob/main/examples/flipper_feature_flags.md)
-- [Paper Trail Whatdunnit](https://github.com/drexed/cmdx/blob/main/examples/paper_trail_whatdunnit.md)
-- [Redis Idempotency](https://github.com/drexed/cmdx/blob/main/examples/redis_idempotency.md)
-- [Sentry Error Tracking](https://github.com/drexed/cmdx/blob/main/examples/sentry_error_tracking.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)