cmdx 1.12.0 → 1.14.0

data/docs/basics/execution.md

@@ -1,96 +0,0 @@
-# Basics - Execution
-
-CMDx offers two execution methods with different error handling approaches. Choose based on your needs: safe result handling or exception-based control flow.
-
-## Execution Methods
-
-Both methods return results, but handle failures differently:
-
-| Method | Returns | Exceptions | Use Case |
-|--------|---------|------------|----------|
-| `execute` | Always returns `CMDx::Result` | Never raises | Predictable result handling |
-| `execute!` | Returns `CMDx::Result` on success | Raises `CMDx::Fault` when skipped or failed | Exception-based control flow |
-
-## Non-bang Execution
-
-Always returns a `CMDx::Result`, never raises exceptions. Perfect for most use cases.
-
-```ruby
-result = CreateAccount.execute(email: "user@example.com")
-
-# Check execution state
-result.success?         #=> true/false
-result.failed?          #=> true/false
-result.skipped?         #=> true/false
-
-# Access result data
-result.context.email    #=> "user@example.com"
-result.state            #=> "complete"
-result.status           #=> "success"
-```
-
-## Bang Execution
-
-Raises `CMDx::Fault` exceptions on failure or skip. Returns results only on success.
-
-| Exception | Raised When |
-|-----------|-------------|
-| `CMDx::FailFault` | Task execution fails |
-| `CMDx::SkipFault` | Task execution is skipped |
-
-!!! warning "Important"
-
-    Behavior depends on `task_breakpoints` or `workflow_breakpoints` config. Default: only failures raise exceptions.
-
-```ruby
-begin
-  result = CreateAccount.execute!(email: "user@example.com")
-  SendWelcomeEmail.execute(result.context)
-rescue CMDx::FailFault => e
-  ScheduleAccountRetryJob.perform_later(e.result.context.email)
-rescue CMDx::SkipFault => e
-  Rails.logger.info("Account creation skipped: #{e.result.reason}")
-rescue Exception => e
-  ErrorTracker.capture(unhandled_exception: e)
-end
-```
-
-## Direct Instantiation
-
-Tasks can be instantiated directly for advanced use cases, testing, and custom execution patterns:
-
-```ruby
-# Direct instantiation
-task = CreateAccount.new(email: "user@example.com", send_welcome: true)
-
-# Access properties before execution
-task.id                      #=> "abc123..." (unique task ID)
-task.context.email           #=> "user@example.com"
-task.context.send_welcome    #=> true
-task.result.state            #=> "initialized"
-task.result.status           #=> "success"
-
-# Manual execution
-task.execute
-# or
-task.execute!
-
-task.result.success?         #=> true/false
-```
-
-## Result Details
-
-The `Result` object provides comprehensive execution information:
-
-```ruby
-result = CreateAccount.execute(email: "user@example.com")
-
-# Execution metadata
-result.id           #=> "abc123..."  (unique execution ID)
-result.task         #=> CreateAccount instance (frozen)
-result.chain        #=> Task execution chain
-
-# Context and metadata
-result.context      #=> Context with all task data
-result.metadata     #=> Hash with execution metadata
-```

data/docs/basics/setup.md

@@ -1,84 +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 ValidateDocument < CMDx::Task
-  def work
-    # Your logic here...
-  end
-
-  def rollback
-    # Your undo logic...
-  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:
-
-!!! 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
-```