cmdx 1.1.0 → 1.1.1

data/docs/basics/context.md

@@ -1,82 +1,127 @@
 # Basics - Context
 
-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.
+Task context provides flexible data storage and sharing for task execution. Built on `LazyStruct`, context enables dynamic attribute access, parameter validation, and seamless data flow between related tasks.
 
 ## Table of Contents
 
 - [TLDR](#tldr)
-- [Loading Parameters](#loading-parameters)
+- [Context Fundamentals](#context-fundamentals)
 - [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)
+- [Context Inspection and Debugging](#context-inspection-and-debugging)
+- [Error Handling](#error-handling)
 
 ## 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
+```ruby
+# Automatic parameter loading
+ProcessOrderTask.call(user_id: 123, amount: 99.99)
+
+# Dynamic attribute access
+context.user_id           # → 123
+context[:amount]          # → 99.99
+
+# Safe modification
+context.total = amount * 1.08
+context.merge!(status: "processed", completed_at: Time.now)
+
+# Task chaining with context preservation
+result = ValidateOrderTask.call(context)
+ProcessPaymentTask.call(result) if result.success?
+```
+
+## Context Fundamentals
 
-## Loading Parameters
+> [!IMPORTANT]
+> Context is automatically populated with all parameters passed to a task. Parameters become accessible as dynamic attributes using both method and hash-style access patterns.
 
-Context is automatically populated when calling tasks with parameters. All
-parameters become accessible as dynamic attributes within the task.
+### Automatic Parameter Loading
+
+When calling tasks, all parameters automatically become context attributes:
 
 ```ruby
-ProcessUserOrderTask.call(
-  user: User.first,
-  order_id: 456,
-  send_notification: true
-)
+class ProcessOrderTask < CMDx::Task
+  required :user_id, type: :integer
+  required :amount, type: :float
+  optional :currency, default: "USD"
+
+  def call
+    # Parameters automatically available in context
+    context.user_id   # → 123
+    context.amount    # → 99.99
+    context.currency  # → "USD"
+  end
+end
+
+ProcessOrderTask.call(user_id: 123, amount: 99.99)
 ```
 
-## Accessing Data
+### Key Normalization
 
-Context provides multiple ways to access stored data with automatic key
-normalization to symbols:
+All keys are automatically normalized to symbols for consistent access:
 
 ```ruby
-class ProcessUserOrderTask < CMDx::Task
+# String and symbol keys both work
+ProcessOrderTask.call("user_id" => 123, :amount => 99.99)
+
+# Both accessible as symbols
+context.user_id  # → 123
+context.amount   # → 99.99
+```
+
+## Accessing Data
 
+Context provides multiple access patterns with automatic nil safety:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
   def call
     # Method-style access (preferred)
-    context.user_id           #=> 123
-    context.send_notification #=> true
+    user_id = context.user_id
+    amount = context.amount
 
     # Hash-style access
-    context[:order_id] #=> 456
-    context["user_id"] #=> 123
+    order_id = context[:order_id]
+    metadata = context["metadata"]
 
     # Safe access with defaults
-    context.fetch!(:priority, "normal") #=> "high"
+    priority = context.fetch!(:priority, "normal")
+    source = context.dig(:metadata, :source)
 
-    # Deep access for nested data
-    context.dig(:metadata, :source) #=> "mobile"
-
-    # Alias for shorter code
-    ctx.user_id #=> 123 (ctx is alias for context)
+    # Shorter alias
+    total = ctx.amount * ctx.tax_rate  # ctx aliases context
   end
-
 end
 ```
 
+> [!NOTE]
+> Accessing undefined attributes returns `nil` instead of raising errors, enabling graceful handling of optional parameters.
+
+### Type Safety
+
+Context accepts any data type without restrictions:
+
+```ruby
+context.string_value  = "Order #12345"
+context.numeric_value = 42
+context.array_value   = [1, 2, 3]
+context.hash_value    = { total: 99.99, tax: 8.99 }
+context.object_value  = User.find(123)
+context.timestamp     = Time.now
+```
+
 ## Modifying Context
 
 Context supports dynamic modification during task execution:
 
 ```ruby
-class ProcessUserOrderTask < CMDx::Task
-
+class ProcessOrderTask < CMDx::Task
   def call
     # Direct assignment
-    context.user = User.find(user_id)
-    context.order = Order.find(order_id)
+    context.user = User.find(context.user_id)
+    context.order = Order.find(context.order_id)
     context.processed_at = Time.now
 
     # Hash-style assignment
@@ -89,185 +134,228 @@ class ProcessUserOrderTask < CMDx::Task
     # Batch updates
     context.merge!(
       status: "completed",
-      processed_by: current_user.id,
+      total_amount: calculate_total,
       completion_time: Time.now
     )
 
-    # Removing data
-    context.delete!(:temporary_data)
+    # Remove sensitive data
+    context.delete!(:credit_card_number)
   end
 
+  private
+
+  def calculate_total
+    context.amount + (context.amount * context.tax_rate)
+  end
 end
 ```
 
 > [!TIP]
-> Use context for both input parameters and intermediate results. This creates
-> a natural data flow through your task execution pipeline.
+> Use context for both input parameters and intermediate results. This creates natural data flow through your task execution pipeline.
 
-## Context Features
+## Data Sharing Between Tasks
 
-### Key Normalization
+Context enables seamless data flow between related tasks in complex workflows:
 
-All keys are automatically converted to symbols for consistent access:
+### Task Composition
 
 ```ruby
-SomeTask.call("user_id" => 123, :order_id => 456)
-
-# Both accessible as symbols
-context.user_id  #=> 123
-context.order_id #=> 456
-```
+class ProcessOrderWorkflowTask < CMDx::Task
+  def call
+    # Validate order data
+    validation_result = ValidateOrderTask.call(context)
+    throw!(validation_result) unless validation_result.success?
 
-### Nil Safety
+    # Process payment with enriched context
+    payment_result = ProcessPaymentTask.call(context)
+    throw!(payment_result) unless payment_result.success?
 
-Accessing undefined attributes returns `nil` instead of raising errors:
+    # Send notifications with complete context
+    NotifyOrderProcessedTask.call(context)
 
-```ruby
-context.undefined_attribute #=> nil
-context[:missing_key]       #=> nil
+    # Context now contains accumulated data from all tasks
+    context.order_validated    # → true (from validation)
+    context.payment_processed  # → true (from payment)
+    context.notification_sent  # → true (from notification)
+  end
+end
 ```
 
-> [!NOTE]
-> Context attributes that are **NOT** loaded will return `nil` rather than
-> raising an error. This allows for graceful handling of optional parameters.
+### Workflow Chains
 
-### Type Flexibility
+```ruby
+# Initialize workflow context
+initial_data = { user_id: 123, product_ids: [1, 2, 3] }
 
-Context accepts any data type without restrictions:
+# Chain tasks with context flow
+validation_result = ValidateCartTask.call(initial_data)
 
-```ruby
-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" }
+if validation_result.success?
+  # Context accumulates data through the chain
+  inventory_result = CheckInventoryTask.call(validation_result.context)
+  payment_result = ProcessPaymentTask.call(inventory_result.context)
+  shipping_result = CreateShipmentTask.call(payment_result.context)
+end
 ```
 
-## Data Sharing Between Tasks
+## Result Object Context Passing
 
-Context objects can be passed between tasks, enabling data flow in complex
-workflows:
+> [!IMPORTANT]
+> CMDx automatically extracts context when Result objects are passed to task methods, enabling powerful workflow compositions where task output becomes the next task's input.
 
-### Within Task Composition
+```ruby
+# Seamless task chaining
+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_records # → [...] (from first task)
+processing_result.context.processed_count   # → 50 (from second task)
+```
+
+### Error Propagation in Chains
 
 ```ruby
-class ProcessUserOrderTask < CMDx::Task
+# Non-raising chain with error handling
+extraction_result = ExtractDataTask.call(source_id: 123)
 
-  def call
-    # Subtasks inherit and modify the same context
-    validation_result = ValidateUserOrderTask.call(context)
-    throw!(validation_result) unless validation_result.success?
+if extraction_result.failed?
+  # Context preserved even in failure scenarios
+  error_handler_result = HandleExtractionErrorTask.call(extraction_result)
+  return error_handler_result
+end
 
-    payment_result = ProcessOrderPaymentTask.call(context)
-    throw!(payment_result) unless payment_result.success?
+# Continue processing with successful result
+ProcessDataTask.call(extraction_result)
+```
 
-    # Context now contains data from all subtasks
-    context.order_validated   #=> true (from ValidateUserOrderTask)
-    context.payment_processed #=> true (from ProcessOrderPaymentTask)
-  end
+### Exception-Based Chains
 
+```ruby
+begin
+  # Raising version propagates exceptions while preserving context
+  extraction_result = ExtractDataTask.call!(source_id: 123)
+  processing_result = ProcessDataTask.call!(extraction_result)
+  notification_result = NotifyCompletionTask.call!(processing_result)
+rescue CMDx::Failed => e
+  # Access failed task's context for error analysis
+  ErrorReportingTask.call(
+    error: e.message,
+    failed_context: e.result.context,
+    user_id: e.result.context.user_id
+  )
 end
 ```
 
-### After Task Completion
+## Context Inspection and Debugging
+
+Context provides comprehensive inspection capabilities for debugging and logging:
 
 ```ruby
-# Chain task results using context
-validation_result = ValidateUserOrderTask.call(user_id: 123, order_id: 456)
+class DebuggableTask < CMDx::Task
+  def call
+    # Log current context state
+    Rails.logger.info "Context: #{context.inspect}"
 
-if validation_result.success?
-  # Pass accumulated context to next task
-  process_result = ProcessUserOrderTask.call(validation_result)
+    # Convert to hash for serialization
+    context_data = context.to_h
+    # → { user_id: 123, amount: 99.99, status: "processing" }
 
-  # Continue chain with enriched context
-  notification_result = SendOrderNotificationTask.call(process_result.context)
+    # Iterate over context data
+    context.each_pair do |key, value|
+      puts "#{key}: #{value.class} = #{value}"
+    end
+
+    # Check for specific keys
+    has_user = context.key?(:user_id)     # → true
+    has_admin = context.key?(:admin_mode) # → false
+  end
 end
 ```
 
-### Workflow Processing
+### Production Logging
 
 ```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
-```
+class OrderProcessingTask < CMDx::Task
+  def call
+    log_context_snapshot("start")
 
-## Result Object Context Passing
+    process_order
 
-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.
+    log_context_snapshot("complete")
+  end
 
-```ruby
-# Chain tasks by passing Result objects
-extraction_result = ExtractDataTask.call(source_id: 123)
-processing_result = ProcessDataTask.call(extraction_result)
+  private
 
-# 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)
+  def log_context_snapshot(stage)
+    Rails.logger.info({
+      stage: stage,
+      task: self.class.name,
+      context: context.to_h.except(:sensitive_data)
+    }.to_json)
+  end
+end
 ```
 
-### Error Handling in Chains
+## Error Handling
+
+> [!WARNING]
+> Context operations are generally safe, but understanding error scenarios helps build robust applications.
 
-Result object chaining works seamlessly with both `call` and `call!` methods:
+### Safe Access Patterns
 
 ```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
+class RobustTask < CMDx::Task
+  def call
+    # Safe: returns nil for missing attributes
+    user_id = context.user_id || 'anonymous'
 
-# 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
-```
+    # Safe: fetch with default
+    timeout = context.fetch!(:timeout, 30)
 
-> [!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.
+    # Safe: deep access with nil protection
+    api_key = context.dig(:credentials, :api_key)
 
-## Context Inspection
+    # Safe: conditional assignment
+    context.processed_at ||= Time.now
+  end
+end
+```
 
-Context provides inspection methods for debugging and logging:
+### Common Error Scenarios
 
 ```ruby
-# Hash representation
-context.to_h #=> { user_id: 123, order_id: 456, ... }
+# Missing required context data
+class PaymentTask < CMDx::Task
+  def call
+    # Check for required context before proceeding
+    unless context.user_id && context.amount
+      context.error_message = "Missing required payment data"
+      fail!(reason: "Cannot process payment")
+    end
 
-# Human-readable inspection
-context.inspect #=> "#<CMDx::Context :user_id=123 :order_id=456>"
+    process_payment
+  end
+end
 
-# Iteration
-context.each_pair { |key, value| puts "#{key}: #{value}" }
+# Invalid context modifications
+class ValidationTask < CMDx::Task
+  def call
+    # Context cannot be replaced entirely
+    # context = {} # This won't work as expected
+
+    # Instead, clear individual keys or use merge!
+    context.delete!(:temporary_data)
+    context.merge!(validation_status: "complete")
+  end
+end
 ```
 
-[Learn more](../../lib/cmdx/lazy_struct.rb)
-about the `LazyStruct` public API that powers context functionality.
+> [!TIP]
+> Use context inspection methods liberally during development and testing. The `to_h` method is particularly useful for logging and debugging complex workflows.
+
+[Learn more](../../lib/cmdx/lazy_struct.rb) about the `LazyStruct` implementation that powers context functionality.
 
 ---