cmdx 0.5.0 → 1.0.0

data/docs/configuration.md

@@ -1,57 +1,187 @@
 # Configuration
 
-Configuration of tasks can be done at global and task levels.
+CMDx provides a flexible configuration system that allows customization at both global and task levels. Configuration follows a hierarchy where global settings serve as defaults that can be overridden at the task level.
 
-## Global settings
+## Table of Contents
 
-Run `rails g cmdx:install` to generate a configuration file within the
-`config/initializers` directory. These settings will be preloaded into all tasks.
+- [Configuration Hierarchy](#configuration-hierarchy)
+- [Global Configuration](#global-configuration)
+  - [Configuration Options](#configuration-options)
+  - [Global Middlewares](#global-middlewares)
+  - [Global Callbacks](#global-callbacks)
+- [Task Settings](#task-settings)
+  - [Available Task Settings](#available-task-settings)
+  - [Workflow Configuration](#workflow-configuration)
+- [Configuration Management](#configuration-management)
+  - [Accessing Configuration](#accessing-configuration)
+  - [Resetting Configuration](#resetting-configuration)
+
+## Configuration Hierarchy
+
+CMDx follows a three-tier configuration hierarchy:
+
+1. **Global Configuration**: Framework-wide defaults
+2. **Task Settings**: Class-level overrides via `task_settings!`
+3. **Runtime Parameters**: Instance-specific overrides during execution
+
+> [!IMPORTANT]
+> Task-level settings take precedence over global configuration. Settings are inherited from superclasses and can be overridden in subclasses.
+
+## Global Configuration
+
+Generate a configuration file using the Rails generator:
+
+```bash
+rails g cmdx:install
+```
+
+This creates `config/initializers/cmdx.rb` with default settings:
 
 ```ruby
 CMDx.configure do |config|
-  # Define which statuses a bang `call!` will halt and raise a fault.
-  # This option can accept an array of statuses.
+  # Halt execution and raise fault on these result statuses when using `call!`
   config.task_halt = CMDx::Result::FAILED
 
-  # Enable task timeouts to prevent call execution beyond a defined threshold.
-  config.task_timeout = nil
-
-  # Define which statuses a batch task will halt execution from proceeding to the next step.
-  # By default skipped tasks are treated as a NOOP so processing is continued.
-  # This option can accept an array of statuses.
-  config.batch_halt = CMDx::Result::FAILED
+  # Stop workflow execution when tasks return these statuses
+  # Note: Skipped tasks continue processing by default
+  config.workflow_halt = CMDx::Result::FAILED
 
-  # Enable batch timeouts to prevent call execution beyond a defined threshold.
-  # TIP: remember to account for all defined tasks when setting this value
-  config.batch_timeout = nil
-
-  # A list of available log formatter can be found at:
+  # Logger with formatter - see available formatters at:
   # https://github.com/drexed/cmdx/tree/main/lib/cmdx/log_formatters
   config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new)
 end
 ```
 
-## Task settings
+### Configuration Options
+
+| Option        | Type                  | Default        | Description |
+|---------------|-----------------------|----------------|-------------|
+| `task_halt`   | String, Array<String> | `"failed"`     | Result statuses that cause `call!` to raise faults |
+| `workflow_halt`  | String, Array<String> | `"failed"`     | Result statuses that halt workflow execution |
+| `logger`      | Logger                | Line formatter | Logger instance for task execution logging |
+| `middlewares` | MiddlewareRegistry    | Empty registry | Global middleware registry applied to all tasks |
+| `callbacks`   | CallbackRegistry      | Empty registry | Global callback registry applied to all tasks |
+
+### Global Middlewares
 
-Finely tune tasks via class level settings.
+Configure middlewares that automatically apply to all tasks in your application:
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+CMDx.configure do |config|
+  # Add middlewares without arguments
+  config.middlewares.use CMDx::Middlewares::Timeout
+
+  # Add middlewares with arguments
+  config.middlewares.use CMDx::Middlewares::Timeout, seconds: 30
+
+  # Add middleware instances
+  config.middlewares.use CMDx::Middlewares::Timeout.new(seconds: 30)
+end
+```
+
+### Global Callbacks
+
+Configure callbacks that automatically apply to all tasks in your application:
+
+```ruby
+CMDx.configure do |config|
+  # Add method callbacks
+  config.callbacks.register :before_execution, :log_task_start
+  config.callbacks.register :after_execution, :log_task_end
+
+  # Add callback instances
+  config.callbacks.register :on_success, NotificationCallback.new([:slack])
+  config.callbacks.register :on_failure, AlertCallback.new(severity: :critical)
+
+  # Add conditional callbacks
+  config.callbacks.register :on_failure, :page_admin, if: :production?
+  config.callbacks.register :before_validation, :skip_validation, unless: :validate_params?
+
+  # Add proc callbacks
+  config.callbacks.register :on_complete, proc { |task, callback_type|
+    Metrics.increment("task.#{task.class.name.underscore}.completed")
+  }
+end
+```
 
-  # Task level settings:
-  task_settings!(task_timeout: 1, tags: ["v1", "DEPRECATED"])
+## Task Settings
+
+Override global configuration for specific tasks or workflows using `task_settings!`:
+
+```ruby
+class ProcessPaymentTask < CMDx::Task
+  task_settings!(
+    task_halt: ["failed"],                       # Only halt on failures
+    tags: ["payments", "critical"],              # Add logging tags
+    logger: Rails.logger,                        # Use Rails logger
+    log_level: :info,                            # Set log level
+    log_formatter: CMDx::LogFormatters::Json.new # JSON formatter
+  )
 
   def call
-    # Do work...
+    # Process payment logic
   end
+end
+```
+
+### Available Task Settings
+
+| Setting         | Type                  | Description |
+|-----------------|-----------------------|-------------|
+| `task_halt`     | String, Array<String> | Result statuses that cause `call!` to raise faults |
+| `workflow_halt`    | String, Array<String> | Result statuses that halt workflow execution |
+| `tags`          | Array<String>         | Tags automatically appended to logs |
+| `logger`        | Logger                | Custom logger instance |
+| `log_level`     | Symbol                | Log level (`:debug`, `:info`, `:warn`, `:error`, `:fatal`) |
+| `log_formatter` | LogFormatter          | Custom log formatter |
 
+### Workflow Configuration
+
+Configure halt behavior for workflows:
+
+```ruby
+class OrderProcessingWorkflow < CMDx::Workflow
+  # Strict workflow - halt on any failure
+  task_settings!(workflow_halt: ["failed", "skipped"])
+
+  process ValidateOrderTask
+  process ChargePaymentTask
+  process FulfillOrderTask
 end
 ```
 
-> [!NOTE]
-> `tags` is a task level setting only. Tags will automatically be appended to logs.
+## Configuration Management
+
+### Accessing Configuration
+
+```ruby
+# Global configuration
+CMDx.configuration.logger      #=> <Logger instance>
+CMDx.configuration.task_halt   #=> "failed"
+CMDx.configuration.middlewares #=> <MiddlewareRegistry instance>
+CMDx.configuration.callbacks   #=> <CallbackRegistry instance>
+
+# Task-specific settings
+class AnalyzeDataTask < CMDx::Task
+  task_settings!(tags: ["analytics"])
+
+  def call
+    tags = task_setting(:tags)               # Gets ["analytics"]
+    halt_statuses = task_setting(:task_halt) # Gets global default
+  end
+end
+```
+
+### Resetting Configuration
+
+Reset configuration to defaults (useful for testing):
+
+```ruby
+CMDx.reset_configuration!
+CMDx.configuration.task_halt #=> "failed" (default)
+```
 
 ---
 
-- **Prev:** [Configuration](https://github.com/drexed/cmdx/blob/main/docs/configuration.md)
-- **Next:** [Basics - Setup](https://github.com/drexed/cmdx/blob/main/docs/basics/setup.md)
+- **Prev:** [Getting Started](getting_started.md)
+- **Next:** [Basics - Setup](basics/setup.md)

data/docs/getting_started.md

@@ -1,47 +1,159 @@
-# Getting Start
+# Getting Started
 
-`CMDx` is a framework for expressive processing of business logic.
+CMDx is a Ruby framework for building maintainable, observable business logic through composable
+command objects. Design robust workflows with automatic parameter validation, structured error
+handling, comprehensive logging, and intelligent execution flow control that scales from simple
+tasks to complex multi-step processes.
 
-Goals:
-- Provide easy branching, nesting, and composition of complex tasks
-- Supply intent, severity, and reasoning to halting execution of tasks
-- Demystify root causes of complex multi-level tasks with exhaustive tracing
+## Table of Contents
 
-## Setup
+- [Installation](#installation)
+- [Quick Setup](#quick-setup)
+- [Execution](#execution)
+- [Result Handling](#result-handling)
+- [Exception Handling](#exception-handling)
+- [Building Workflows](#building-workflows)
+- [Code Generation](#code-generation)
+
+## Installation
+
+Add CMDx to your Gemfile:
+
+```ruby
+gem 'cmdx'
+```
+
+For Rails applications, generate the configuration:
+
+```bash
+rails generate cmdx:install
+```
+
+> [!NOTE]
+> This creates `config/initializers/cmdx.rb` with default settings.
+
+## Quick Setup
 
 ```ruby
 class ProcessOrderTask < CMDx::Task
+  required :order_id, type: :integer
+  optional :send_email, type: :boolean, default: true
 
   def call
-    fail!(reason: "Order was canceled") if context.order.canceled?
-    skip!(reason: "Order is processing") if context.order.processing?
+    context.order = Order.find(order_id)
 
-    inform_partner_warehouses
-    send_confirmation_email
+    if context.order.canceled?
+      fail!(reason: "Order canceled", canceled_at: context.order.canceled_at)
+    elsif context.order.completed?
+      skip!(reason: "Already processed")
+    else
+      context.order.update!(status: 'completed', completed_at: Time.now)
+      EmailService.send_confirmation(context.order) if send_email
+    end
   end
-
 end
 ```
 
+> [!TIP]
+> Use **present tense verbs** for clarity: `ProcessOrderTask`, `SendEmailTask`, `ValidatePaymentTask`
+
 ## Execution
 
+Execute tasks using class methods:
+
+```ruby
+# Returns Result object
+result = ProcessOrderTask.call(order_id: 123)
+
+# Raises exceptions on failure/skip, else returns Result object
+result = ProcessOrderTask.call!(order_id: 123, send_email: false)
+```
+
+## Result Handling
+
+Check execution outcomes:
+
+```ruby
+result = ProcessOrderTask.call(order_id: 123)
+
+case result.status
+when 'success'
+  redirect_to order_path(result.context.order), notice: "Order processed!"
+when 'skipped'
+  redirect_to order_path(result.context.order), notice: result.metadata[:reason]
+when 'failed'
+  redirect_to orders_path, alert: "Error: #{result.metadata[:reason]}"
+end
+
+# Access execution metadata
+puts "Runtime: #{result.runtime}s, Task ID: #{result.id}"
+```
+
+## Exception Handling
+
+Use `call!` for exception-based control flow:
+
 ```ruby
-result = ProcessOrderTask.call(order: order)
+begin
+  result = ProcessOrderTask.call!(order_id: 123)
+  redirect_to order_path(result.context.order), notice: "Success!"
+rescue CMDx::Skipped => e
+  redirect_to orders_path, notice: e.result.metadata[:reason]
+rescue CMDx::Failed => e
+  redirect_to order_path(123), alert: e.result.metadata[:reason]
+end
 ```
 
-## Result
+## Building Workflows
+
+Combine tasks using workflows:
 
 ```ruby
-if result.failed?
-  flash[:error] = "Failed! #{result.metadata[:reason]}"
-elsif result.skipped?
-  flash[:notice] = "FYI: #{result.metadata[:reason]}"
-else
-  flash[:success] = "Order successfully processed"
+class OrderProcessingWorkflow < CMDx::Workflow
+  required :order_id, type: :integer
+
+  before_execution :log_workflow_start
+  on_failed :notify_support
+
+  process ValidateOrderTask
+  process ChargePaymentTask
+  process UpdateInventoryTask
+  process SendConfirmationTask, if: proc { context.payment_successful? }
+
+  # NO call method
+
+  private
+
+  def log_workflow_start
+    Rails.logger.info "Starting order workflow for order #{order_id}"
+  end
+
+  def notify_support
+    SupportNotifier.alert("Order workflow failed", context: context.to_h)
+  end
 end
+
+result = ProcessOrderWorkflow.call(order_id: 123)
 ```
 
+## Code Generation
+
+Generate tasks and workflows with proper structure:
+
+```bash
+# Generate individual task
+rails generate cmdx:task ProcessOrder
+# Creates: app/cmds/process_order_task.rb
+
+# Generate task workflow
+rails generate cmdx:workflow OrderDeliveryWorkflow
+# Creates: app/cmds/order_delivery_workflow.rb
+```
+
+> [!NOTE]
+> Generators automatically handle naming conventions and inherit from `ApplicationTask`/`ApplicationWorkflow` when available.
+
 ---
 
-- **Prev:** [Example](https://github.com/drexed/cmdx/blob/main/docs/example.md)
-- **Next:** [Configuration](https://github.com/drexed/cmdx/blob/main/docs/configuration.md)
+- **Prev:** [Tips and Tricks](tips_and_tricks.md)
+- **Next:** [Configuration](configuration.md)

data/docs/interruptions/exceptions.md

@@ -1,29 +1,207 @@
 # Interruptions - Exceptions
 
-## Non-bang call
+CMDx provides robust exception handling that differs between the `call` and `call!`
+methods. Understanding how unhandled exceptions are processed is crucial for
+building reliable task execution flows and implementing proper error handling strategies.
 
-Any unhandled exception will be caught and halted using `fail!`.
-The original exception will be passed as metadata of the result object.
+## Table of Contents
+
+- [Exception Handling Behavior](#exception-handling-behavior)
+- [Bang Call (`call!`)](#bang-call-call)
+- [Exception Classification](#exception-classification)
+
+## Exception Handling Behavior
+
+### Non-bang Call (`call`)
+
+The `call` method captures **all** unhandled exceptions and converts them to
+failed results, ensuring that no exceptions escape the task execution boundary.
+This provides consistent, predictable behavior for result processing.
 
 ```ruby
-result = ProcessOrderTask.call
+class ProcessUserOrderTask < CMDx::Task
+
+  def call
+    # This will raise a NoMethodError
+    undefined_method_call
+  end
+
+end
+
+result = ProcessUserOrderTask.call
 result.state    #=> "interrupted"
 result.status   #=> "failed"
+result.failed?  #=> true
 result.metadata #=> {
-                #=>   reason: "[RuntimeError] method xyz is not defined",
-                #=>   original_exception: <RuntimeError message="method xyz is not defined">
+                #=>   reason: "[NoMethodError] undefined method `undefined_method_call`",
+                #=>   original_exception: <NoMethodError>
                 #=> }
 ```
 
-## Bang call
+> [!NOTE]
+> The `call` method ensures no exceptions escape task execution, making it ideal
+> for workflow processing and scenarios where you need guaranteed result objects.
+
+### Exception Metadata Structure
+
+Captured exceptions populate result metadata with structured information:
+
+```ruby
+class ConnectDatabaseTask < CMDx::Task
+
+  def call
+    # Simulate a database connection error
+    raise ActiveRecord::ConnectionNotEstablished, "Database unavailable"
+  end
+
+end
+
+result = ConnectDatabaseTask.call
+
+# Exception information in metadata
+result.metadata[:reason]                       #=> "[ActiveRecord::ConnectionNotEstablished] Database unavailable"
+result.metadata[:original_exception]           #=> <ActiveRecord::ConnectionNotEstablished>
+result.metadata[:original_exception].class     #=> ActiveRecord::ConnectionNotEstablished
+result.metadata[:original_exception].message   #=> "Database unavailable"
+result.metadata[:original_exception].backtrace #=> ["..."]
+```
+
+### Accessing Original Exception Details
+
+```ruby
+result = ProcessUserOrderTask.call
+
+if result.failed? && result.metadata[:original_exception]
+  original = result.metadata[:original_exception]
+
+  puts "Exception type: #{original.class}"
+  puts "Exception message: #{original.message}"
+  puts "Exception backtrace:"
+  puts original.backtrace.first(5).join("\n")
+
+  # Check exception type for specific handling
+  case original
+  when ActiveRecord::RecordNotFound
+    handle_missing_record(original)
+  when Net::TimeoutError
+    handle_timeout_error(original)
+  when StandardError
+    handle_generic_error(original)
+  end
+end
+```
+
+## Bang Call (`call!`)
+
+The `call!` method allows unhandled exceptions to propagate **unless** they are
+CMDx faults that match the `task_halt` configuration. This enables exception-based
+control flow while still providing structured fault handling.
+
+```ruby
+class ProcessUserOrderTask < CMDx::Task
+
+  def call
+    # This will raise a NoMethodError directly
+    undefined_method_call
+  end
+
+end
+
+begin
+  ProcessUserOrderTask.call!
+rescue NoMethodError => e
+  puts "Caught original exception: #{e.message}"
+  # Handle the original exception directly
+end
+```
+
+### Fault vs Exception Behavior
+
+```ruby
+class ProcessOrderPaymentTask < CMDx::Task
+
+  def call
+    if context.simulate_fault
+      fail!(reason: "Controlled failure") # Becomes CMDx::Failed
+    else
+      raise StandardError, "Uncontrolled error" # Remains StandardError
+    end
+  end
+
+end
+
+# Fault behavior (controlled)
+begin
+  ProcessOrderPaymentTask.call!(simulate_fault: true)
+rescue CMDx::Failed => e
+  puts "Caught CMDx fault: #{e.message}"
+end
+
+# Exception behavior (uncontrolled)
+begin
+  ProcessOrderPaymentTask.call!(simulate_fault: false)
+rescue StandardError => e
+  puts "Caught standard exception: #{e.message}"
+end
+```
+
+## Exception Classification
+
+### Protected Exceptions
 
-Any unhandled exception from a `call!` method will be raised as is.
+Certain CMDx-specific exceptions are always allowed to propagate and are never
+converted to failed results:
 
 ```ruby
-ProcessOrderTask.call! #=> raises NoMethodError, "method xyz is not defined"
+class ProcessUndefinedOrderTask < CMDx::Task
+  # Intentionally not implementing call method
+end
+
+# These exceptions always propagate regardless of call method
+begin
+  ProcessUndefinedOrderTask.call
+rescue CMDx::UndefinedCallError => e
+  puts "This exception is never converted to a failed result"
+end
+
+begin
+  ProcessUndefinedOrderTask.call!
+rescue CMDx::UndefinedCallError => e
+  puts "This exception propagates normally in call! too"
+end
 ```
 
+### CMDx Fault Handling
+
+CMDx faults have special handling in both call methods:
+
+```ruby
+class ProcessOrderWithHaltTask < CMDx::Task
+  # Configure to halt on failures
+  task_settings!(task_halt: [CMDx::Result::FAILED])
+
+  def call
+    fail!(reason: "This is a controlled failure")
+  end
+end
+
+# With call - fault becomes failed result
+result = ProcessOrderWithHaltTask.call
+result.failed? #=> true
+
+# With call! - fault becomes exception (due to task_halt configuration)
+begin
+  ProcessOrderWithHaltTask.call!
+rescue CMDx::Failed => e
+  puts "Fault converted to exception: #{e.message}"
+end
+```
+
+> [!IMPORTANT]
+> Always preserve original exception information in metadata when handling
+> exceptions manually. This maintains debugging capabilities and error traceability.
+
 ---
 
-- **Prev:** [Interruptions - Faults](https://github.com/drexed/cmdx/blob/main/docs/interruptions/faults.md)
-- **Next:** [Outcomes - Result](https://github.com/drexed/cmdx/blob/main/docs/outcomes/result.md)
+- **Prev:** [Interruptions - Faults](faults.md)
+- **Next:** [Outcomes - Result](../outcomes/result.md)