cmdx 1.13.0 → 1.14.0

data/docs/basics/setup.md

@@ -1,107 +0,0 @@
-# Basics - Setup
-
-Tasks are the heart of CMDx—self-contained units of business logic with built-in validation, error handling, and execution tracking.
-
-## Structure
-
-Tasks need only two things: inherit from `CMDx::Task` and define a `work` method:
-
-```ruby
-class ValidateDocument < CMDx::Task
-  def work
-    # Your logic here...
-  end
-end
-```
-
-Without a `work` method, execution raises `CMDx::UndefinedMethodError`.
-
-```ruby
-class IncompleteTask < CMDx::Task
-  # No `work` method defined
-end
-
-IncompleteTask.execute #=> raises CMDx::UndefinedMethodError
-```
-
-## Rollback
-
-Undo any operations linked to the given status, helping to restore a pristine state.
-
-```ruby
-class ChargeCard < CMDx::Task
-  def work
-    # Your logic here, ex: charge $100
-  end
-
-  # Called automatically if a later step in the workflow fails
-  def rollback
-    # Your undo logic, ex: void $100 charge
-  end
-end
-```
-
-## Inheritance
-
-Share configuration across tasks using inheritance:
-
-```ruby
-class ApplicationTask < CMDx::Task
-  register :middleware, SecurityMiddleware
-
-  before_execution :initialize_request_tracking
-
-  attribute :session_id
-
-  private
-
-  def initialize_request_tracking
-    context.tracking_id ||= SecureRandom.uuid
-  end
-end
-
-class SyncInventory < ApplicationTask
-  def work
-    # Your logic here...
-  end
-end
-```
-
-## Lifecycle
-
-Tasks follow a predictable execution pattern:
-
-```mermaid
-stateDiagram-v2
-    Initialized: Instantiation
-    Initialized --> Validating: execute
-    Validating --> Executing: Valid?
-    Validating --> Failed: Invalid
-    Executing --> Success: Work done
-    Executing --> Skipped: skip!
-    Executing --> Failed: fail! / Exception
-    Executed
-
-    state Executed {
-        Success
-        Skipped
-        Failed
-        Rollback
-
-        Skipped --> Rollback
-        Failed --> Rollback
-    }
-```
-
-!!! danger "Caution"
-
-    Tasks are single-use objects. Once executed, they're frozen and immutable.
-
-| Stage | State | Status | Description |
-|-------|-------|--------|-------------|
-| **Instantiation** | `initialized` | `success` | Task created with context |
-| **Validation** | `executing` | `success`/`failed` | Attributes validated |
-| **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

@@ -1,157 +0,0 @@
-# Callbacks
-
-Run custom logic at specific points during task execution. Callbacks have full access to task context and results, making them perfect for logging, notifications, cleanup, and more.
-
-See [Global Configuration](getting_started.md#callbacks) for framework-wide callback setup.
-
-!!! warning "Important"
-
-    Callbacks execute in declaration order (FIFO). Multiple callbacks of the same type run sequentially.
-
-## Available Callbacks
-
-Callbacks execute in a predictable lifecycle order:
-
-```ruby
-1. before_validation           # Pre-validation setup
-2. before_execution            # Prepare for execution
-
-# --- Task#work executes ---
-
-3. on_[complete|interrupted]   # State-based (execution lifecycle)
-4. on_executed                 # Always runs after work completes
-5. on_[success|skipped|failed] # Status-based (business outcome)
-6. on_[good|bad]               # Outcome-based (success/skip vs fail)
-```
-
-## Declarations
-
-### Symbol References
-
-Reference instance methods by symbol for simple callback logic:
-
-```ruby
-class ProcessBooking < CMDx::Task
-  before_execution :find_reservation
-
-  # Batch declarations (works for any type)
-  on_complete :notify_guest, :update_availability
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def find_reservation
-    @reservation ||= Reservation.find(context.reservation_id)
-  end
-
-  def notify_guest
-    GuestNotifier.call(context.guest, result)
-  end
-
-  def update_availability
-    AvailabilityService.update(context.room_ids, result)
-  end
-end
-```
-
-### Proc or Lambda
-
-Use anonymous functions for inline callback logic:
-
-```ruby
-class ProcessBooking < CMDx::Task
-  # Proc
-  on_interrupted proc { ReservationSystem.pause! }
-
-  # Lambda
-  on_complete -> { ReservationSystem.resume! }
-end
-```
-
-### Class or Module
-
-Implement reusable callback logic in dedicated modules and classes:
-
-```ruby
-class BookingConfirmationCallback
-  def call(task)
-    if task.result.success?
-      MessagingApi.send_confirmation(task.context.guest)
-    else
-      MessagingApi.send_issue_alert(task.context.manager)
-    end
-  end
-end
-
-class ProcessBooking < CMDx::Task
-  # Class or Module
-  on_success BookingConfirmationCallback
-
-  # Instance
-  on_interrupted BookingConfirmationCallback.new
-end
-```
-
-### Conditional Execution
-
-Control callback execution with conditional logic:
-
-```ruby
-class MessagingPermissionCheck
-  def call(task)
-    task.context.guest.can?(:receive_messages)
-  end
-end
-
-class ProcessBooking < CMDx::Task
-  # If and/or Unless
-  before_execution :notify_guest, if: :messaging_enabled?, unless: :messaging_blocked?
-
-  # Proc
-  on_failure :increment_failure, if: -> { Rails.env.production? && self.class.name.include?("Legacy") }
-
-  # Lambda
-  on_success :ping_housekeeping, if: proc { context.rooms_need_cleaning? }
-
-  # Class or Module
-  on_complete :send_confirmation, unless: MessagingPermissionCheck
-
-  # Instance
-  on_complete :send_confirmation, if: MessagingPermissionCheck.new
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def messaging_enabled?
-    context.guest.messaging_preference == true
-  end
-
-  def messaging_blocked?
-    context.guest.communication_status == :blocked
-  end
-end
-```
-
-## Callback Removal
-
-Remove unwanted callbacks dynamically:
-
-!!! warning "Important"
-
-    Each `deregister` call removes one callback. Use multiple calls for batch removals.
-
-```ruby
-class ProcessBooking < CMDx::Task
-  # Symbol
-  deregister :callback, :before_execution, :notify_guest
-
-  # Class or Module (no instances)
-  deregister :callback, :on_complete, BookingConfirmationCallback
-end
-```

data/docs/configuration.md

@@ -1,314 +0,0 @@
-# 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
-```

data/docs/deprecation.md

@@ -1,143 +0,0 @@
-# Task Deprecation
-
-Manage legacy tasks gracefully with built-in deprecation support. Choose how to handle deprecated tasks—log warnings for awareness, issue Ruby warnings for development, or prevent execution entirely.
-
-## Modes
-
-### Raise
-
-Prevent task execution completely. Perfect for tasks that must no longer run.
-
-!!! warning
-
-    Use `:raise` mode carefully—it will break existing workflows immediately.
-
-```ruby
-class ProcessObsoleteAPI < CMDx::Task
-  settings(deprecated: :raise)
-
-  def work
-    # Will never execute...
-  end
-end
-
-result = ProcessObsoleteAPI.execute
-#=> raises CMDx::DeprecationError: "ProcessObsoleteAPI usage prohibited"
-```
-
-### Log
-
-Allow execution while tracking deprecation in logs. Ideal for gradual migrations.
-
-```ruby
-class ProcessLegacyFormat < CMDx::Task
-  settings(deprecated: :log)
-  settings(deprecated: true)
-
-  def work
-    # Executes but logs deprecation warning...
-  end
-end
-
-result = ProcessLegacyFormat.execute
-result.successful? #=> true
-
-# Deprecation warning appears in logs:
-# WARN -- : DEPRECATED: ProcessLegacyFormat - migrate to replacement or discontinue use
-```
-
-### Warn
-
-Issue Ruby warnings visible during development and testing. Keeps production logs clean while alerting developers.
-
-```ruby
-class ProcessOldData < CMDx::Task
-  settings(deprecated: :warn)
-
-  def work
-    # Executes but emits Ruby warning...
-  end
-end
-
-result = ProcessOldData.execute
-result.successful? #=> true
-
-# Ruby warning appears in stderr:
-# [ProcessOldData] DEPRECATED: migrate to a replacement or discontinue use
-```
-
-## Declarations
-
-### Symbol or String
-
-```ruby
-class OutdatedConnector < CMDx::Task
-  # Symbol
-  settings(deprecated: :raise)
-
-  # String
-  settings(deprecated: "warn")
-end
-```
-
-### Boolean or Nil
-
-```ruby
-class OutdatedConnector < CMDx::Task
-  # Deprecates with default :log mode
-  settings(deprecated: true)
-
-  # Skips deprecation
-  settings(deprecated: false)
-  settings(deprecated: nil)
-end
-```
-
-### Method
-
-```ruby
-class OutdatedConnector < CMDx::Task
-  # Symbol
-  settings(deprecated: :deprecated?)
-
-  def work
-    # Your logic here...
-  end
-
-  private
-
-  def deprecated?
-    Time.now.year > 2024 ? :raise : false
-  end
-end
-```
-
-### Proc or Lambda
-
-```ruby
-class OutdatedConnector < CMDx::Task
-  # Proc
-  settings(deprecated: proc { Rails.env.development? ? :raise : :log })
-
-  # Lambda
-  settings(deprecated: -> { Current.tenant.legacy_mode? ? :warn : :raise })
-end
-```
-
-### Class or Module
-
-```ruby
-class OutdatedTaskDeprecator
-  def call(task)
-    task.class.name.include?("Outdated")
-  end
-end
-
-class OutdatedConnector < CMDx::Task
-  # Class or Module
-  settings(deprecated: OutdatedTaskDeprecator)
-
-  # Instance
-  settings(deprecated: OutdatedTaskDeprecator.new)
-end
-```