cmdx 0.5.0 → 1.0.1

data/docs/basics/call.md

@@ -1,31 +1,251 @@
 # Basics - Call
 
-Calling a task executes the logic within it. Tasks can only be executed via
-the `call` and `call!` class methods.
+Calling a task executes the business logic within it. Tasks provide two execution methods that handle success and failure scenarios differently. Understanding when to use each method is crucial for proper error handling and control flow.
 
-## Non-bang
+## Table of Contents
 
-The `call` method will always return a `CMDx::Result` object after execution.
+- [TLDR](#tldr)
+- [Execution Methods Overview](#execution-methods-overview)
+- [Non-bang Call (`call`)](#non-bang-call-call)
+- [Bang Call (`call!`)](#bang-call-call)
+- [Direct Instantiation](#direct-instantiation)
+- [Parameter Passing](#parameter-passing)
+- [Result Propagation (`throw!`)](#result-propagation-throw)
+- [Result Callbacks](#result-callbacks)
+- [Task State Lifecycle](#task-state-lifecycle)
+- [Return Value Details](#return-value-details)
+
+## TLDR
+
+- **`call`** - Always returns `CMDx::Result`, never raises exceptions (preferred)
+- **`call!`** - Returns `CMDx::Result` on success, raises `CMDx::Fault` on failure/skip
+- **Results** - Check status with `result.success?`, `result.failed?`, `result.skipped?`
+- **Callbacks** - Chain results with `.on_success`, `.on_failed`, `.on_skipped`
+- **Propagation** - Use `throw!(other_result)` to bubble up failures from subtasks
+
+## Execution Methods Overview
+
+| Method | Returns | Exceptions | Use Case |
+|--------|---------|------------|----------|
+| `call` | Always returns `CMDx::Result` | Never raises | Predictable result handling |
+| `call!` | Returns `CMDx::Result` on success | Raises `CMDx::Fault` on failure/skip | Exception-based control flow |
+
+## Non-bang Call (`call`)
+
+The `call` method always returns a `CMDx::Result` object regardless of execution outcome. This is the preferred method for most use cases.
+
+```ruby
+result = ProcessOrderTask.call(order_id: 12345)
+
+# Check execution state
+result.success?         #=> true/false
+result.failed?          #=> true/false
+result.skipped?         #=> true/false
+
+# Access result data
+result.context.order_id #=> 12345
+result.runtime          #=> 0.05 (seconds)
+result.state            #=> "complete"
+result.status           #=> "success"
+```
+
+### Handling Different Outcomes
+
+```ruby
+result = ProcessOrderTask.call(order_id: 12345)
+
+case result.status
+when "success"
+  puts "Order processed: #{result.context.order_id}"
+when "skipped"
+  puts "Order skipped: #{result.metadata[:reason]}"
+when "failed"
+  puts "Order failed: #{result.metadata[:reason]}"
+end
+```
+
+## Bang Call (`call!`)
+
+The bang `call!` method raises a `CMDx::Fault` exception when tasks fail or are skipped, based on the `task_halt` configuration. It returns a `CMDx::Result` object only on success. This method is useful in scenarios where you want exception-based control flow.
+
+```ruby
+begin
+  result = ProcessOrderTask.call!(order_id: 12345)
+  puts "Order processed: #{result.context.order_id}"
+rescue CMDx::Failed => e
+  # Handle failure
+  RetryOrderJob.perform_later(e.result.context.order_id)
+rescue CMDx::Skipped => e
+  # Handle skip
+  Rails.logger.info("Order skipped: #{e.result.metadata[:reason]}")
+end
+```
+
+### Exception Types
+
+| Exception | Raised When | Purpose |
+|-----------|-------------|---------|
+| `CMDx::Failed` | Task execution fails | Handle failure scenarios |
+| `CMDx::Skipped` | Task execution is skipped | Handle skip scenarios |
+
+## Direct Instantiation
+
+Tasks can be instantiated directly for advanced use cases, testing, and custom execution patterns:
+
+```ruby
+# Direct instantiation
+task = ProcessOrderTask.new(order_id: 12345, notify_customer: true)
+
+# Access properties before execution
+task.id                      #=> "abc123..." (unique task ID)
+task.context.order_id        #=> 12345
+task.context.notify_customer #=> true
+task.result.state            #=> "initialized"
+
+# Manual execution
+task.perform
+task.result.success?         #=> true/false
+```
+
+### Execution Approaches
+
+| Approach | Use Case | Benefits |
+|----------|----------|----------|
+| `TaskClass.call(...)` | Standard execution | Simple, handles full lifecycle |
+| `TaskClass.call!(...)` | Exception-based flow | Automatic fault raising |
+| `TaskClass.new(...).perform` | Advanced scenarios | Full control, testing flexibility |
+
+> [!NOTE]
+> Direct instantiation gives you access to the task instance before and after execution, but you must call the execution method manually.
+
+## Parameter Passing
+
+All methods accept parameters that become available in the task context:
+
+```ruby
+# Direct parameters
+result = ProcessOrderTask.call(
+  order_id: 12345,
+  notify_customer: true,
+  priority: "high"
+)
+
+# From another task result
+validation_result = ValidateOrderTask.call(order_id: 12345)
+
+# -- Passing Result object
+result = ProcessOrderTask.call!(validation_result)
+
+# -- Passing context directly
+result = ProcessOrderTask.new(validation_result.context)
+```
+
+## Result Propagation (`throw!`)
+
+The `throw!` method enables result propagation, allowing tasks to bubble up failures from subtasks while preserving the original fault information:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  def call
+    validation_result = ValidateOrderTask.call(context)
+    throw!(validation_result) if validation_result.failed?
+
+    payment_result = ProcessPaymentTask.call(context)
+    throw!(payment_result) if payment_result.skipped?
+
+    delivery_result = ScheduleDeliveryTask.call(context)
+    throw!(delivery_result) # failed or skipped
+
+    # Continue with main logic
+    context.order = Order.find(context.order_id)
+    finalize_order_processing
+  end
+end
+```
+
+## Result Callbacks
+
+Results support fluent callback patterns for conditional logic:
 
 ```ruby
-ProcessOrderTask.call #=> <CMDx::Result ...>
+ProcessOrderTask
+  .call(order_id: 12345)
+  .on_success { |result|
+    SendOrderConfirmationTask.call(result.context)
+  }
+  .on_failed { |result|
+    Honeybadger.notify(result.metadata[:error])
+  }
+  .on_executed { |result|
+    StatsD.timing('order.processing_time', result.runtime)
+  }
 ```
 
-## Bang
+### Available Callbacks
 
-The bang `call!` method raises a `CMDx::Fault` based exception depending on the defined
-`task_halt` status options, otherwise it will return a `CMDx::Result` object. This
-form of call is useful in background jobs where retries are done via the exception mechanism.
+```ruby
+result = ProcessOrderTask.call(order_id: 12345)
+
+# State-based callbacks
+result
+  .on_complete { |r| cleanup_resources(r) }
+  .on_interrupted { |r| handle_interruption(r) }
+  .on_executed { |r| log_execution_time(r) }
+
+# Status-based callbacks
+result
+  .on_success { |r| handle_success(r) }
+  .on_skipped { |r| handle_skip(r) }
+  .on_failed { |r| handle_failure(r) }
+
+# Outcome-based callbacks
+result
+  .on_good { |r| log_positive_outcome(r) }
+  .on_bad { |r| log_negative_outcome(r) }
+```
+
+## Task State Lifecycle
+
+Tasks progress through defined states during execution:
 
 ```ruby
-ProcessOrderTask.call! #=> raises CMDx::Failed
+result = ProcessOrderTask.call(order_id: 12345)
+
+# Execution states
+result.state #=> "initialized" -> "executing" -> "complete"/"interrupted"
+
+# Outcome statuses
+result.status #=> "success"/"failed"/"skipped"
+```
+
+## Return Value Details
+
+The `Result` object provides comprehensive execution information:
+
+```ruby
+result = ProcessOrderTask.call(order_id: 12345)
+
+# Execution metadata
+result.id           #=> "abc123..."  (unique execution ID)
+result.runtime      #=> 0.05         (execution time in seconds)
+result.task         #=> ProcessOrderTask instance
+result.chain        #=> Chain object for tracking executions
+
+# Context and metadata
+result.context      #=> Context with all task data
+result.metadata     #=> Hash with execution metadata
+
+# State checking methods
+result.good?        #=> true for success/skipped
+result.bad?         #=> true for failed/skipped
+result.complete?    #=> true when execution finished
+result.interrupted? #=> true for failed/skipped
 ```
 
 > [!IMPORTANT]
-> Tasks are single use objects, once they have been called they are frozen and cannot be called again
-> as result object will be returned. Build a new task call to execute a new instance of the same task.
+> Tasks are single-use objects. Once executed, they are frozen and cannot be called again. Create a new task instance to execute the same task again.
 
 ---
 
-- **Prev:** [Basics - Setup](https://github.com/drexed/cmdx/blob/main/docs/basics/setup.md)
-- **Next:** [Basics - Context](https://github.com/drexed/cmdx/blob/main/docs/basics/context.md)
+- **Prev:** [Basics - Setup](setup.md)
+- **Next:** [Basics - Context](context.md)

data/docs/basics/chain.md

@@ -0,0 +1,280 @@
+# Basics - Chain
+
+A chain represents a collection of related task executions that share a common execution context. Chains provide unified tracking, indexing, and reporting for task workflows using thread-local storage to automatically group related tasks without manual coordination.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Thread-Local Chain Management](#thread-local-chain-management)
+- [Automatic Chain Creation](#automatic-chain-creation)
+- [Chain Inheritance](#chain-inheritance)
+- [Chain Structure and Metadata](#chain-structure-and-metadata)
+- [Correlation ID Integration](#correlation-id-integration)
+- [State Delegation](#state-delegation)
+- [Serialization and Logging](#serialization-and-logging)
+
+## TLDR
+
+- **Chains** - Automatically group related task executions within the same thread
+- **Thread-local** - Each thread gets its own chain, no manual coordination needed
+- **Inheritance** - Subtasks automatically join the current thread's chain
+- **Correlation** - Chain IDs serve as correlation identifiers for tracing
+- **Access** - Use `result.chain.id` and `result.chain.results` to inspect execution trails
+
+## Thread-Local Chain Management
+
+Chains use thread-local storage to automatically group related task executions within the same thread while maintaining isolation across different threads:
+
+```ruby
+# Each thread gets its own chain context
+Thread.new do
+  result = ProcessOrderTask.call(order_id: 123)
+  result.chain.id    # => unique ID for this thread
+end
+
+Thread.new do
+  result = ProcessOrderTask.call(order_id: 456)
+  result.chain.id    # => different unique ID
+end
+
+# Access the current thread's chain
+CMDx::Chain.current  # => current chain or nil
+CMDx::Chain.clear    # => clears current thread's chain
+```
+
+## Automatic Chain Creation
+
+Every task execution automatically creates or joins a thread-local chain context:
+
+```ruby
+# Single task creates its own chain
+result = ProcessUserOrderTask.call(order_id: 123)
+result.chain.id           #=> "018c2b95-b764-7615-a924-cc5b910ed1e5"
+result.chain.results.size #=> 1
+
+# Subsequent tasks in the same thread join the existing chain
+result2 = AnotherTask.call(data: "test")
+result2.chain.id == result.chain.id  #=> true
+result2.chain.results.size           #=> 2
+```
+
+## Chain Inheritance
+
+When tasks call other tasks within the same thread, they automatically inherit the current chain, creating a cohesive execution trail:
+
+```ruby
+class ProcessUserOrderTask < CMDx::Task
+  def call
+    context.order = Order.find(order_id)
+
+    # Subtasks automatically inherit the current thread's chain
+    SendOrderConfirmationTask.call(order_id: order_id)
+    NotifyWarehousePartnersTask.call(order_id: order_id)
+  end
+end
+
+result = ProcessUserOrderTask.call(order_id: 123)
+chain = result.chain
+
+# All related tasks share the same chain automatically
+chain.results.size #=> 3
+chain.results.map(&:task).map(&:class)
+#=> [ProcessUserOrderTask, SendOrderConfirmationTask, NotifyWarehousePartnersTask]
+```
+
+> [!NOTE]
+> Tasks automatically inherit the current thread's chain, creating a unified execution trail for debugging and monitoring purposes without any manual chain management.
+
+## Chain Structure and Metadata
+
+Chains provide comprehensive execution information:
+
+```ruby
+result = ProcessUserOrderTask.call(order_id: 123)
+chain = result.chain
+
+# Chain identification
+chain.id      #=> "018c2b95-b764-7615-a924-cc5b910ed1e5"
+chain.results #=> [<CMDx::Result ...>, <CMDx::Result ...>]
+
+# Execution state (delegates to outer most result)
+chain.state   #=> "complete"
+chain.status  #=> "success"
+chain.outcome #=> "success"
+chain.runtime #=> 0.5
+```
+
+## Correlation ID Integration
+
+Chains automatically integrate with the correlation tracking system through thread-local storage, providing seamless request tracing across task boundaries. The chain ID serves as the correlation identifier, enabling you to trace execution flows through distributed systems and complex business logic.
+
+### Custom Chain IDs
+
+You can specify custom chain IDs for specific correlation contexts:
+
+```ruby
+# Create a chain with custom ID
+chain = CMDx::Chain.new(id: "user-session-123")
+CMDx::Chain.current = chain
+
+result = ProcessUserOrderTask.call(order_id: 123)
+result.chain.id #=> "user-session-123"
+```
+
+### Automatic Correlation Inheritance
+
+Chains inherit correlation IDs using a hierarchical precedence system:
+
+```ruby
+# 1. Existing chain ID takes precedence
+CMDx::Chain.current = CMDx::Chain.new(id: "custom-correlation-123")
+result = ProcessUserOrderTask.call(order_id: 123)
+result.chain.id #=> "custom-correlation-123"
+
+# 2. Thread-local correlation ID is used if no chain exists
+CMDx::Chain.clear
+CMDx::Correlator.id = "thread-correlation-456"
+result = ProcessUserOrderTask.call
+result.chain.id #=> "thread-correlation-456"
+
+# 3. Generated UUID when no correlation exists
+CMDx::Correlator.clear
+result = ProcessUserOrderTask.call
+result.chain.id #=> "018c2b95-b764-7615-a924-cc5b910ed1e5" (generated)
+```
+
+### Cross-Task Correlation Propagation
+
+When tasks call subtasks within the same thread, correlation IDs automatically propagate:
+
+```ruby
+class ProcessUserOrderTask < CMDx::Task
+  def call
+    context.order = Order.find(order_id)
+
+    # Subtasks inherit the same correlation ID automatically
+    SendOrderConfirmationTask.call(order_id: order_id)
+    NotifyWarehousePartnersTask.call(order_id: order_id)
+  end
+end
+
+# Set correlation for this execution context
+CMDx::Chain.current = CMDx::Chain.new(id: "user-order-correlation-123")
+
+result = ProcessUserOrderTask.call(order_id: 456)
+chain = result.chain
+
+# All tasks share the same correlation ID
+chain.id #=> "user-order-correlation-123"
+chain.results.all? { |r| r.chain.id == "user-order-correlation-123" } #=> true
+```
+
+### Correlation Context Management
+
+Use correlation blocks to manage correlation scope:
+
+```ruby
+# Correlation applies only within the block
+CMDx::Correlator.use("api-request-789") do
+  result = ProcessApiRequestTask.call(request_data: data)
+  result.chain.id #=> "api-request-789"
+
+  # Nested task calls inherit the same correlation
+  AuditLogTask.call(audit_data: data)
+end
+
+# Outside the block, correlation context is restored
+result = AnotherTask.call
+result.chain.id #=> different correlation ID
+```
+
+### Middleware Integration
+
+The `CMDx::Middlewares::Correlate` middleware automatically manages correlation contexts during task execution:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  # Apply correlate middleware globally or per-task
+  use CMDx::Middlewares::Correlate
+
+  def call
+    # Correlation is automatically managed
+    # Chain ID reflects the established correlation context
+  end
+end
+```
+
+> [!TIP]
+> Chain IDs serve as correlation identifiers, making it easy to trace related operations across your application. The thread-local storage ensures automatic correlation without manual chain management.
+
+> [!NOTE]
+> Correlation IDs are particularly useful for debugging distributed systems, API request tracing, and understanding complex business workflows. All logs and results automatically include the chain ID for correlation.
+
+## State Delegation
+
+Chain state information delegates to the first (outer most) result, representing the overall execution outcome:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+  def call
+    ValidateOrderDataTask.call!(order_id: order_id)   # Success
+    ProcessOrderPaymentTask.call!(order_id: order_id) # Failed
+  end
+end
+
+result = ProcessOrderTask.call
+chain = result.chain
+
+# Chain status reflects the main task, not subtasks
+chain.status            #=> "failed" (ProcessOrderPaymentTask failed)
+chain.state             #=> "interrupted"
+
+# Individual task results maintain their own state
+chain.results[0].status #=> "failed"  (ProcessOrderTask)
+chain.results[1].status #=> "success" (ValidateOrderDataTask)
+chain.results[2].status #=> "failed"  (ProcessOrderPaymentTask)
+```
+
+> [!IMPORTANT]
+> Chain state always reflects the first (outer most) task outcome, not the subtasks. Individual subtask results maintain their own success/failure states.
+
+## Serialization and Logging
+
+Chains provide comprehensive serialization capabilities for monitoring and debugging:
+
+```ruby
+result = ProcessUserOrderTask.call(order_id: 123)
+chain = result.chain
+
+# Hash representation with all execution data
+chain.to_h
+#=> {
+#     id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+#     state: "complete",
+#     status: "success",
+#     outcome: "success",
+#     runtime: 0.5,
+#     results: [
+#       { class: "ProcessUserOrderTask", state: "complete", status: "success", ... },
+#       { class: "SendOrderConfirmationTask", state: "complete", status: "success", ... },
+#       { class: "NotifyWarehousePartnersTask", state: "complete", status: "success", ... }
+#     ]
+#   }
+
+# Human-readable summary
+puts chain.to_s
+#   chain: 018c2b95-b764-7615-a924-cc5b910ed1e5
+#   ================================================
+#
+#   ProcessUserOrderTask: index=0 state=complete status=success ...
+#   SendOrderConfirmationTask: index=1 state=complete status=success ...
+#   NotifyWarehousePartnersTask: index=2 state=complete status=success ...
+#
+#   ================================================
+#   state: complete | status: success | outcome: success | runtime: 0.5
+```
+
+---
+
+- **Prev:** [Basics - Context](context.md)
+- **Next:** [Interruptions - Halt](../interruptions/halt.md)