cmdx 1.13.0 → 1.14.0

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)

data/docs/workflows.md

@@ -1,226 +0,0 @@
-# Workflows
-
-Compose multiple tasks into powerful, sequential pipelines. Workflows provide a declarative way to build complex business processes with conditional execution, shared context, and flexible error handling.
-
-## Declarations
-
-Tasks run in declaration order (FIFO), sharing a common context across the pipeline.
-
-!!! warning
-
-    Don't define a `work` method in workflows—the module handles execution automatically.
-
-### Task
-
-```ruby
-class OnboardingWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task CreateUserProfile
-  task SetupAccountPreferences
-
-  tasks SendWelcomeEmail, SendWelcomeSms, CreateDashboard
-end
-```
-
-!!! tip
-
-    Execute tasks in parallel via the [cmdx-parallel](https://github.com/drexed/cmdx-parallel) gem.
-
-### Group
-
-Group related tasks to share configuration:
-
-!!! warning "Important"
-
-    Settings and conditionals apply to all tasks in the group.
-
-```ruby
-class ContentModerationWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  # Screening phase
-  tasks ScanForProfanity, CheckForSpam, ValidateImages, breakpoints: ["skipped"]
-
-  # Review phase
-  tasks ApplyFilters, ScoreContent, FlagSuspicious
-
-  # Decision phase
-  tasks PublishContent, QueueForReview, NotifyModerators
-end
-```
-
-### Conditionals
-
-Conditionals support multiple syntaxes for flexible execution control:
-
-```ruby
-class ContentAccessCheck
-  def call(task)
-    task.context.user.can?(:publish_content)
-  end
-end
-
-class OnboardingWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  # If and/or Unless
-  task SendWelcomeEmail, if: :email_configured?, unless: :email_disabled?
-
-  # Proc
-  task SendWelcomeEmail, if: -> { Rails.env.production? && self.class.name.include?("Premium") }
-
-  # Lambda
-  task SendWelcomeEmail, if: proc { context.features_enabled? }
-
-  # Class or Module
-  task SendWelcomeEmail, unless: ContentAccessCheck
-
-  # Instance
-  task SendWelcomeEmail, if: ContentAccessCheck.new
-
-  # Conditional applies to all tasks of this declaration group
-  tasks SendWelcomeEmail, CreateDashboard, SetupTutorial, if: :email_configured?
-
-  private
-
-  def email_configured?
-    context.user.email_address == true
-  end
-
-  def email_disabled?
-    context.user.communication_preference == :disabled
-  end
-end
-```
-
-## Halt Behavior
-
-By default, skipped tasks don't stop the workflow—they're treated as no-ops. Configure breakpoints globally or per-task to customize this behavior.
-
-```ruby
-class AnalyticsWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task CollectMetrics      # If fails → workflow stops
-  task FilterOutliers      # If skipped → workflow continues
-  task GenerateDashboard   # Only runs if no failures occurred
-end
-```
-
-### Task Configuration
-
-Configure halt behavior for the entire workflow:
-
-```ruby
-class SecurityWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  # Halt on both failed and skipped results
-  settings(workflow_breakpoints: ["skipped", "failed"])
-
-  task PerformSecurityScan
-  task ValidateSecurityRules
-end
-
-class OptionalTasksWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  # Never halt, always continue
-  settings(breakpoints: [])
-
-  task TryBackupData
-  task TryCleanupLogs
-  task TryOptimizeCache
-end
-```
-
-### Group Configuration
-
-Different task groups can have different halt behavior:
-
-```ruby
-class SubscriptionWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task CreateSubscription, ValidatePayment, workflow_breakpoints: ["skipped", "failed"]
-
-  # Never halt, always continue
-  task SendConfirmationEmail, UpdateBilling, breakpoints: []
-end
-```
-
-## Nested Workflows
-
-Build hierarchical workflows by composing workflows within workflows:
-
-```ruby
-class EmailPreparationWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task ValidateRecipients
-  task CompileTemplate
-end
-
-class EmailDeliveryWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  tasks SendEmails, TrackDeliveries
-end
-
-class CompleteEmailWorkflow < CMDx::Task
-  include CMDx::Workflow
-
-  task EmailPreparationWorkflow
-  task EmailDeliveryWorkflow, if: proc { context.preparation_successful? }
-  task GenerateDeliveryReport
-end
-```
-
-## Parallel Execution
-
-Run tasks concurrently using the [Parallel](https://github.com/grosser/parallel) gem. It automatically uses all available processors for maximum throughput.
-
-!!! warning
-
-    Context is read-only during parallel execution. Load all required data beforehand.
-
-```ruby
-class SendWelcomeNotifications < CMDx::Task
-  include CMDx::Workflow
-
-  # Default options (dynamically calculated to available processors)
-  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel
-
-  # Fix number of threads
-  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_threads: 2
-
-  # Fix number of forked processes
-  tasks SendWelcomeEmail, SendWelcomeSms, SendWelcomePush, strategy: :parallel, in_processes: 2
-
-  # NOTE: Reactors are not supported
-end
-```
-
-## Task Generator
-
-Generate new CMDx workflow tasks quickly using the built-in generator:
-
-```bash
-rails generate cmdx:workflow SendNotifications
-```
-
-This creates a new workflow task file with the basic structure:
-
-```ruby
-# app/tasks/send_notifications.rb
-class SendNotifications < CMDx::Task
-  include CMDx::Workflow
-
-  tasks Task1, Task2
-end
-```
-
-!!! tip
-
-    Use **present tense verbs + pluralized noun** for workflow task names, eg: `SendNotifications`, `DownloadFiles`, `ValidateDocuments`

data/examples/active_record_database_transaction.md

@@ -1,27 +0,0 @@
-# Active Record Query Tagging
-
-Wrap task or workflow execution in a database transaction. This is essential for data integrity when multiple steps modify the database.
-
-### Setup
-
-```ruby
-# lib/cmdx_database_transaction_middleware.rb
-class CmdxDatabaseTransactionMiddleware
-  def self.call(task, **options, &)
-    ActiveRecord::Base.transaction(requires_new: true, &)
-  end
-end
-```
-
-### Usage
-
-```ruby
-class MyTask < CMDx::Task
-  register :middleware, CmdxDatabaseTransactionMiddleware
-
-  def work
-    # Do work...
-  end
-
-end
-```