cmdx 0.5.0 → 1.0.1

data/docs/basics/context.md

@@ -1,67 +1,275 @@
 # Basics - Context
 
-The task `context` provides a form of storage to the task objects themselves.
+The task `context` provides flexible data storage and sharing for task objects.
+Built on `LazyStruct`, context enables dynamic attribute access, parameter
+validation, and seamless data flow between related tasks.
 
-## Loading
+## Table of Contents
 
-Loading a task with data is as simple as passing objects in a key value format.
-The context object is a custom version of an [OpenStruct](https://github.com/ruby/ostruct)
-called a `LazyStruct` with no limitations for what can be stored.
+- [TLDR](#tldr)
+- [Loading Parameters](#loading-parameters)
+- [Accessing Data](#accessing-data)
+- [Modifying Context](#modifying-context)
+- [Context Features](#context-features)
+- [Data Sharing Between Tasks](#data-sharing-between-tasks)
+- [Result Object Context Passing](#result-object-context-passing)
+- [Context Inspection](#context-inspection)
+
+## TLDR
+
+- **Dynamic attributes** - Access data with `context.user_id` or `context[:user_id]`
+- **Automatic loading** - Parameters become context attributes automatically
+- **Modification** - Assign data with `context.user = User.find(id)`
+- **Sharing** - Pass context between tasks with `SomeTask.call(context)`
+- **Nil safety** - Missing attributes return `nil` instead of raising errors
+
+## Loading Parameters
+
+Context is automatically populated when calling tasks with parameters. All
+parameters become accessible as dynamic attributes within the task.
 
 ```ruby
-ProcessOrderTask.call(email: "bob@bigcorp.com", order: order)
+ProcessUserOrderTask.call(
+  user: User.first,
+  order_id: 456,
+  send_notification: true
+)
 ```
 
-## Access
+## Accessing Data
 
-Tasks with a loaded context can be accessed within a task itself. Read, set and
-alter the context attributes anywhere within the task object.
+Context provides multiple ways to access stored data with automatic key
+normalization to symbols:
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessUserOrderTask < CMDx::Task
 
   def call
-    # Reading from context storage:
-    context.email #=> "bob@bigcorp.com"
-    ctx.order     #=> <Order #a1b2c3d>
-    context.idk   #=> nil
-
-    # Writing to context storage:
-    context.first_name = "Bob"
-    ctx.middle_name ||= "Biggie"
-    context.merge!(last_name: "Boomer")
+    # Method-style access (preferred)
+    context.user_id           #=> 123
+    context.send_notification #=> true
+
+    # Hash-style access
+    context[:order_id] #=> 456
+    context["user_id"] #=> 123
+
+    # Safe access with defaults
+    context.fetch!(:priority, "normal") #=> "high"
+
+    # Deep access for nested data
+    context.dig(:metadata, :source) #=> "mobile"
+
+    # Alias for shorter code
+    ctx.user_id #=> 123 (ctx is alias for context)
   end
 
 end
 ```
 
-[Learn more](https://github.com/drexed/cmdx/blob/main/lib/cmdx/lazy_struct.rb)
-about the `LazyStruct` public API for interacting with the context.
+## Modifying Context
+
+Context supports dynamic modification during task execution:
+
+```ruby
+class ProcessUserOrderTask < CMDx::Task
+
+  def call
+    # Direct assignment
+    context.user = User.find(user_id)
+    context.order = Order.find(order_id)
+    context.processed_at = Time.now
+
+    # Hash-style assignment
+    context[:status] = "processing"
+    context["result_code"] = "SUCCESS"
+
+    # Conditional assignment
+    context.notification_sent ||= false
+
+    # Batch updates
+    context.merge!(
+      status: "completed",
+      processed_by: current_user.id,
+      completion_time: Time.now
+    )
+
+    # Removing data
+    context.delete!(:temporary_data)
+  end
+
+end
+```
+
+> [!TIP]
+> Use context for both input parameters and intermediate results. This creates
+> a natural data flow through your task execution pipeline.
+
+## Context Features
+
+### Key Normalization
+
+All keys are automatically converted to symbols for consistent access:
+
+```ruby
+SomeTask.call("user_id" => 123, :order_id => 456)
+
+# Both accessible as symbols
+context.user_id  #=> 123
+context.order_id #=> 456
+```
+
+### Nil Safety
+
+Accessing undefined attributes returns `nil` instead of raising errors:
+
+```ruby
+context.undefined_attribute #=> nil
+context[:missing_key]       #=> nil
+```
 
 > [!NOTE]
-> Attributes that are **NOT** loaded into the context will return `nil`.
+> Context attributes that are **NOT** loaded will return `nil` rather than
+> raising an error. This allows for graceful handling of optional parameters.
 
-## Passing
+### Type Flexibility
 
-Context objects can be passed to other tasks which allows you to build small tasks
-that passes data around as part of a higher level task.
+Context accepts any data type without restrictions:
 
 ```ruby
-# Within task:
-class ProcessOrderTask < CMDx::Task
+context.string_value  = "Order processed"
+context.numeric_value = 42
+context.array_value   = [1, 2, 3]
+context.hash_value    = { total: 99.99, currency: "USD" }
+context.object_value  = User.find(123)
+context.proc_value    = -> { "dynamic value" }
+```
+
+## Data Sharing Between Tasks
+
+Context objects can be passed between tasks, enabling data flow in complex
+workflows:
+
+### Within Task Composition
+
+```ruby
+class ProcessUserOrderTask < CMDx::Task
 
   def call
-    SendEmailConfirmationTask.call(context)
+    # Subtasks inherit and modify the same context
+    validation_result = ValidateUserOrderTask.call(context)
+    throw!(validation_result) unless validation_result.success?
+
+    payment_result = ProcessOrderPaymentTask.call(context)
+    throw!(payment_result) unless payment_result.success?
+
+    # Context now contains data from all subtasks
+    context.order_validated   #=> true (from ValidateUserOrderTask)
+    context.payment_processed #=> true (from ProcessOrderPaymentTask)
   end
 
 end
+```
+
+### After Task Completion
+
+```ruby
+# Chain task results using context
+validation_result = ValidateUserOrderTask.call(user_id: 123, order_id: 456)
+
+if validation_result.success?
+  # Pass accumulated context to next task
+  process_result = ProcessUserOrderTask.call(validation_result)
+
+  # Continue chain with enriched context
+  notification_result = SendOrderNotificationTask.call(process_result.context)
+end
+```
+
+### Workflow Processing
+
+```ruby
+# Context maintains continuity across workflow operations
+initial_context = {
+  user_id: 123,
+  action: "bulk_order_processing"
+}
+
+results = [
+  ValidateOrderDataTask.call(initial_context),
+  ProcessOrderPaymentTask.call(initial_context),
+  UpdateInventoryTask.call(initial_context)
+]
+
+# All tasks share and modify the same context data
+results.first.context.validation_completed #=> true
+results.last.context.inventory_updated     #=> true
+```
+
+## Result Object Context Passing
+
+CMDx supports automatic context extraction when Result objects are passed to task
+`new` or `call` methods. This enables seamless task chaining where the output of
+one task becomes the input for the next, creating powerful workflow compositions.
+
+```ruby
+# Chain tasks by passing Result objects
+extraction_result = ExtractDataTask.call(source_id: 123)
+processing_result = ProcessDataTask.call(extraction_result)
+
+# Context flows automatically between tasks
+processing_result.context.source_id         #=> 123 (from first task)
+processing_result.context.extracted_data    #=> [data...] (from first task)
+processing_result.context.extraction_time   #=> 2024-01-01 10:00:00 (from first task)
+processing_result.context.processed_data    #=> [processed...] (from second task)
+processing_result.context.processing_time   #=> 2024-01-01 10:00:05 (from second task)
+```
+
+### Error Handling in Chains
+
+Result object chaining works seamlessly with both `call` and `call!` methods:
+
+```ruby
+# Non-raising version (returns failed results)
+extraction_result = ExtractDataTask.call(source_id: 123)
+if extraction_result.failed?
+  # Handle failure, but can still pass context to error handler
+  error_result = HandleErrorTask.call(extraction_result)
+end
 
-# After call:
-result = ProcessOrderTask.call(email: "bob@bigcorp.com", order: order)
-NotifyPartnerWarehousesTask.call(result.ctx)
+# Raising version (propagates exceptions)
+begin
+  extraction_result = ExtractDataTask.call!(source_id: 123)
+  processing_result = ProcessDataTask.call!(extraction_result)
+rescue CMDx::Failed => e
+  # Handle any failure in the chain
+  error_result = HandleErrorTask.call(e.result)
+end
 ```
 
+> [!TIP]
+> Result object chaining is particularly powerful when combined with [Workflows](../workflows.md)
+> processing, where multiple tasks can operate on shared context while maintaining
+> individual result tracking.
+
+## Context Inspection
+
+Context provides inspection methods for debugging and logging:
+
+```ruby
+# Hash representation
+context.to_h #=> { user_id: 123, order_id: 456, ... }
+
+# Human-readable inspection
+context.inspect #=> "#<CMDx::Context :user_id=123 :order_id=456>"
+
+# Iteration
+context.each_pair { |key, value| puts "#{key}: #{value}" }
+```
+
+[Learn more](../../lib/cmdx/lazy_struct.rb)
+about the `LazyStruct` public API that powers context functionality.
+
 ---
 
-- **Prev:** [Basics - Call](https://github.com/drexed/cmdx/blob/main/docs/basics/call.md)
-- **Next:** [Basics - Run](https://github.com/drexed/cmdx/blob/main/docs/basics/run.md)
+- **Prev:** [Basics - Call](call.md)
+- **Next:** [Basics - Chain](chain.md)

data/docs/basics/setup.md

@@ -1,32 +1,105 @@
 # Basics - Setup
 
-A task represents a unit of work to execute. While `CMDx` offers a plethora
-of features, a `call` method is the only thing required to execute a task.
+A task represents a unit of work to execute. Tasks are the core building blocks
+of CMDx, encapsulating business logic within a structured, reusable object. While
+CMDx offers extensive features like parameter validation, callbacks, and state tracking,
+only a `call` method is required to create a functional task.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Basic Task Structure](#basic-task-structure)
+- [Task Execution](#task-execution)
+- [Inheritance and Application Tasks](#inheritance-and-application-tasks)
+- [Generator](#generator)
+- [Task Lifecycle](#task-lifecycle)
+
+## TLDR
+
+- **Tasks** - Ruby classes that inherit from `CMDx::Task` with a `call` method
+- **Structure** - Only `call` method required, everything else is optional
+- **Execution** - Run with `MyTask.call(params)` to get a `CMDx::Result`
+- **Generator** - Use `rails g cmdx:task MyTask` to create task templates
+- **Single-use** - Tasks are frozen after execution, create new instances for each run
+
+## Basic Task Structure
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
+class ProcessUserOrderTask < CMDx::Task
 
   def call
-    # Do work...
+    # Your business logic here
+    context.order = Order.find(context.order_id)
+    context.order.process!
   end
 
   private
 
-  # Business logic...
+  # Support methods and business logic
 
 end
 ```
 
-> [!TIP]
-> While complexity designed into a task is up to the engineer, it's
-> suggested that tasks be small and composed into higher level tasks.
+## Task Execution
+
+```ruby
+# Execute a task
+result = ProcessUserOrderTask.call(order_id: 123)
+
+# Access the result
+result.success?      #=> true
+result.context.order #=> <Order id: 123>
+```
+
+## Inheritance and Application Tasks
+
+In Rails applications, tasks typically inherit from an `ApplicationTask` base class:
+
+```ruby
+# app/tasks/application_task.rb
+class ApplicationTask < CMDx::Task
+  # Shared configuration and functionality
+end
+
+# app/tasks/process_user_order_task.rb
+class ProcessUserOrderTask < ApplicationTask
+  def call
+    # Implementation
+  end
+end
+```
 
 ## Generator
 
-Run `rails g cmdx:task [NAME]` to create a task template file under `app/cmds`.
-Tasks will inherit from `ApplicationTask` if available or fall back to `CMDx::Task`.
+Rails applications can use the built-in generator to create task templates:
+
+```bash
+rails g cmdx:task ProcessUserOrder
+```
+
+This creates `app/tasks/process_user_order_task.rb` with:
+- Proper inheritance from `ApplicationTask` (if available) or `CMDx::Task`
+- Basic structure with parameter definitions
+- Template implementation
+
+> [!TIP]
+> Use the generator to maintain consistent task structure and naming conventions across your application.
+
+## Task Lifecycle
+
+Every task follows a predictable lifecycle:
+
+1. **Instantiation** - Task object created with context
+2. **Validation** - Parameters validated against definitions
+3. **Execution** - The `call` method runs business logic
+4. **Completion** - Result finalized with state and status
+5. **Freezing** - Task becomes immutable after execution
+
+> [!IMPORTANT]
+> Tasks are single-use objects. Once executed, they are frozen and cannot
+> be called again. Create a new task instance for each execution.
 
 ---
 
-- **Prev:** [Configuration](https://github.com/drexed/cmdx/blob/main/docs/configuration.md)
-- **Next:** [Basics - Call](https://github.com/drexed/cmdx/blob/main/docs/basics/call.md)
+- **Prev:** [Configuration](../configuration.md)
+- **Next:** [Basics - Call](call.md)

data/docs/callbacks.md

@@ -0,0 +1,283 @@
+# Callbacks
+
+Callbacks (callbacks) provide precise control over task execution lifecycle, running custom logic at
+specific transition points. Callback callables have access to the same context and result information
+as the `call` method, enabling rich integration patterns.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Overview](#overview)
+- [Callback Declaration](#callback-declaration)
+- [Callback Classes](#callback-classes)
+- [Available Callbacks](#available-callbacks)
+  - [Validation Callbacks](#validation-callbacks)
+  - [Execution Callbacks](#execution-callbacks)
+  - [State Callbacks](#state-callbacks)
+  - [Status Callbacks](#status-callbacks)
+  - [Outcome Callbacks](#outcome-callbacks)
+- [Execution Order](#execution-order)
+- [Conditional Execution](#conditional-execution)
+- [Callback Inheritance](#callback-inheritance)
+
+## TLDR
+
+- **Purpose** - Execute custom logic at specific points in task lifecycle
+- **Declaration** - Use method names, procs, class instances, or blocks
+- **Callback types** - Validation, execution, state, status, and outcome callbacks
+- **Execution order** - Runs in precise lifecycle order (before_execution → validation → call → status → after_execution)
+- **Conditional** - Support `:if` and `:unless` options for conditional execution
+- **Inheritance** - Callbacks are inherited, perfect for global patterns
+
+> [!TIP]
+> Callbacks are inheritable, making them perfect for setting up global logic execution patterns like tracking markers, account plan checks, or logging standards.
+
+## Overview
+
+Callbacks can be declared in multiple ways: method names, procs/lambdas, Callback class instances, or blocks.
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  # Method name declaration
+  after_validation :verify_order_data
+
+  # Proc/lambda declaration
+  on_complete -> { send_telemetry_data }
+
+  # Callback class declaration
+  before_execution LoggingCallback.new(:debug)
+  on_success NotificationCallback.new([:email, :slack])
+
+  # Multiple callbacks for same event
+  on_success :increment_counter, :send_notification
+
+  # Conditional execution
+  on_failed :alert_support, if: :critical_order?
+  after_execution :cleanup_resources, unless: :preserve_data?
+
+  # Block declaration
+  before_execution do
+    context.processing_start = Time.now
+  end
+
+  def call
+    context.order = Order.find(order_id)
+    context.order.process!
+  end
+
+  private
+
+  def critical_order?
+    context.order.value > 10_000
+  end
+
+  def preserve_data?
+    Rails.env.development?
+  end
+end
+```
+
+## Callback Classes
+
+For complex callback logic or reusable patterns, you can create Callback classes similar to Middleware classes. Callback classes inherit from `CMDx::Callback` and implement the `call(task, callback_type)` method.
+
+### Creating Callback Classes
+
+```ruby
+class NotificationCallback < CMDx::Callback
+  def initialize(channels)
+    @channels = Array(channels)
+  end
+
+  def call(task, callback_type)
+    return unless callback_type == :on_success
+
+    @channels.each do |channel|
+      NotificationService.send(channel, "Task #{task.class.name} completed")
+    end
+  end
+end
+```
+
+### Registering Callback Classes
+
+Callback classes can be registered using the `register` class method (recommended) or by directly calling the CallbackRegistry:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  # Recommended: Use the register class method
+  register :before_execution, LoggingCallback.new(:debug)
+  register :on_success, NotificationCallback.new([:email, :slack])
+  register :on_failure, :alert_admin, if: :critical?
+
+  # Alternative: Direct CallbackRegistry access (less common)
+  # cmd_callbacks.register(:after_execution, CleanupCallback.new)
+
+  # Traditional callback definitions still work alongside Callback classes
+  before_validation :validate_order_data
+  on_success :update_metrics
+
+  def call
+    context.order = Order.find(order_id)
+    context.order.process!
+  end
+
+  private
+
+  def critical?
+    context.order.value > 10_000
+  end
+end
+```
+
+## Available Callbacks
+
+### Validation Callbacks
+
+Execute around parameter validation:
+
+- `before_validation` - Before parameter validation
+- `after_validation` - After successful parameter validation
+
+### Execution Callbacks
+
+Execute around task logic:
+
+- `before_execution` - Before task logic begins
+- `after_execution` - After task logic completes (success or failure)
+
+### State Callbacks
+
+Execute based on execution state:
+
+- `on_executing` - Task begins running
+- `on_complete` - Task completes successfully
+- `on_interrupted` - Task is halted (skip/failure)
+- `on_executed` - Task finishes (complete or interrupted)
+
+### Status Callbacks
+
+Execute based on execution status:
+
+- `on_success` - Task succeeds
+- `on_skipped` - Task is skipped
+- `on_failed` - Task fails
+
+### Outcome Callbacks
+
+Execute based on outcome classification:
+
+- `on_good` - Positive outcomes (success or skipped)
+- `on_bad` - Negative outcomes (skipped or failed)
+
+## Execution Order
+
+Callbacks execute in precise order during task lifecycle:
+
+> [!IMPORTANT]
+> Multiple callbacks of the same type execute in declaration order (FIFO: first in, first out).
+
+```ruby
+1. before_execution            # Setup and preparation
+2. on_executing                # Task begins running
+3. before_validation           # Pre-validation setup
+4. after_validation            # Post-validation logic
+5. [call method]               # Your business logic
+6. on_[complete|interrupted]   # Based on execution state
+7. on_executed                 # Task finished (any outcome)
+8. on_[success|skipped|failed] # Based on execution status
+9. on_[good|bad]               # Based on outcome classification
+10. after_execution            # Cleanup and finalization
+```
+
+> [!IMPORTANT]
+> Multiple callbacks of the same type execute in declaration order (FIFO: first in, first out).
+
+## Conditional Execution
+
+Callbacks support conditional execution through `:if` and `:unless` options:
+
+| Option    | Description |
+| --------- | ----------- |
+| `:if`     | Execute callback only if condition is truthy |
+| `:unless` | Execute callback only if condition is falsy |
+
+```ruby
+class ProcessPaymentTask < CMDx::Task
+  # Method name condition
+  on_success :send_receipt, if: :email_enabled?
+
+  # Proc condition
+  on_failure :retry_payment, if: -> { retry_count < 3 }
+
+  # String condition (evaluated as method)
+  after_execution :log_metrics, unless: "Rails.env.test?"
+
+  # Multiple conditions
+  on_complete :expensive_operation, if: :production_env?, unless: :maintenance_mode?
+
+  private
+
+  def email_enabled?
+    context.user.email_notifications?
+  end
+
+  def production_env?
+    Rails.env.production?
+  end
+
+  def maintenance_mode?
+    SystemStatus.maintenance_mode?
+  end
+end
+```
+
+## Callback Inheritance
+
+Callbacks are inherited from parent classes, enabling application-wide patterns:
+
+```ruby
+class ApplicationTask < CMDx::Task
+  before_execution :log_task_start  # All tasks get execution logging
+  after_execution :log_task_end     # All tasks get completion logging
+  on_failed :report_failure         # All tasks get error reporting
+  on_success :track_success_metrics # All tasks get success tracking
+
+  private
+
+  def log_task_start
+    Rails.logger.info "Starting #{self.class.name}"
+  end
+
+  def log_task_end
+    Rails.logger.info "Finished #{self.class.name} in #{result.runtime}s"
+  end
+
+  def report_failure
+    ErrorReporter.notify(result.metadata)
+  end
+
+  def track_success_metrics
+    Metrics.increment("task.#{self.class.name.underscore}.success")
+  end
+end
+
+class ProcessOrderTask < ApplicationTask
+  before_validation :load_order                     # Specific to order processing
+  on_success :send_confirmation                     # Domain-specific success action
+  on_failed :refund_payment, if: :payment_captured? # Order-specific failure handling
+
+  def call
+    # Inherits all ApplicationTask callbacks plus order-specific ones
+    context.order.process!
+  end
+end
+```
+
+> [!TIP]
+> Callbacks are inherited by subclasses, making them ideal for setting up global lifecycle patterns across all tasks in your application.
+
+---
+
+- **Prev:** [Parameters - Defaults](parameters/defaults.md)
+- **Prev:** [Middlewares](middlewares.md)