cmdx 1.1.2 → 1.5.0

data/docs/interruptions/halt.md

@@ -1,184 +1,141 @@
 # Interruptions - Halt
 
-Halting stops execution of a task with explicit intent signaling. Tasks provide two primary halt methods that control execution flow and result in different outcomes, each serving specific use cases in business logic.
+Halting stops task execution with explicit intent signaling. Tasks provide two primary halt methods that control execution flow and result in different outcomes.
 
 ## Table of Contents
 
-- [TLDR](#tldr)
-- [Skip (`skip!`)](#skip-skip)
-- [Fail (`fail!`)](#fail-fail)
+- [Skipping](#skipping)
+- [Failing](#failing)
 - [Metadata Enrichment](#metadata-enrichment)
 - [State Transitions](#state-transitions)
-- [Exception Behavior](#exception-behavior)
-- [Error Handling](#error-handling)
-- [The Reason Key](#the-reason-key)
+- [Execution Behavior](#execution-behavior)
+  - [Non-bang execution](#non-bang-execution)
+  - [Bang execution](#bang-execution)
+- [Best Practices](#best-practices)
 
-## TLDR
+## Skipping
 
-```ruby
-# Skip when task shouldn't execute (not an error)
-skip!(reason: "Order already processed")
-
-# Fail when task encounters error condition
-fail!(reason: "Insufficient funds", error_code: "PAYMENT_DECLINED")
-
-# With structured metadata
-skip!(
-  reason: "User inactive",
-  user_id: 123,
-  last_active: "2023-01-01"
-)
-
-# Exception behavior with call vs call!
-result = Task.call(params)    # Returns result object
-Task.call!(params)            # Raises CMDx::Skipped/Failed on halt
-```
-
-## Skip (`skip!`)
-
-> [!NOTE]
-> Use `skip!` when a task cannot or should not execute under current conditions, but this is not an error. Skipped tasks are considered successful outcomes.
-
-The `skip!` method indicates that a task did not meet the criteria to continue execution. This represents a controlled, intentional interruption where the task determines that execution is not necessary or appropriate.
+`skip!` communicates that the task is to be intentionally bypassed. This represents a controlled, intentional interruption where the task determines that execution is not necessary or appropriate.
 
-### Basic Usage
+> [!IMPORTANT]
+> Skipping is a no-op, not a failure or error and are considered successful outcomes.
 
 ```ruby
-class ProcessOrderTask < CMDx::Task
-  required :order_id, type: :integer
-
-  def call
-    context.order = Order.find(order_id)
+class ProcessInventory < CMDx::Task
+  def work
+    # Without a reason
+    skip! if Array(ENV["DISABLED_TASKS"]).include?(self.class.name)
 
-    # Skip if order already processed
-    skip!(reason: "Order already processed") if context.order.processed?
+    # With a reason
+    skip!("Warehouse closed") unless Time.now.hour.between?(8, 18)
 
-    # Skip if prerequisites not met
-    skip!(reason: "Payment method required") unless context.order.payment_method
+    inventory = Inventory.find(context.inventory_id)
 
-    # Continue with business logic
-    context.order.process!
+    if inventory.already_counted?
+      skip!("Inventory already counted today")
+    else
+      inventory.count!
+    end
   end
 end
-```
 
-### Common Skip Scenarios
+result = ProcessInventory.execute(inventory_id: 456)
 
-| Scenario | Example |
-|----------|---------|
-| **Already processed** | `skip!(reason: "User already verified")` |
-| **Prerequisites missing** | `skip!(reason: "Required documents not uploaded")` |
-| **Business rules** | `skip!(reason: "Outside business hours")` |
-| **State conditions** | `skip!(reason: "Account suspended")` |
+# Executed
+result.status #=> "skipped"
 
-## Fail (`fail!`)
+# Without a reason
+result.reason #=> "no reason given"
 
-> [!IMPORTANT]
-> Use `fail!` when a task encounters an error that prevents successful completion. Failed tasks represent error conditions that need to be handled or corrected.
+# With a reason
+result.reason #=> "Warehouse closed"
+```
 
-The `fail!` method indicates that a task encountered an error condition that prevents successful completion. This represents controlled failure where the task explicitly determines that execution cannot continue.
+## Failing
 
-### Basic Usage
+`fail!` communicates that the task encountered an impediment that prevents successful completion. This represents controlled failure where the task explicitly determines that execution cannot continue.
 
 ```ruby
-class ProcessPaymentTask < CMDx::Task
-  required :payment_id, type: :integer
-
-  def call
-    context.payment = Payment.find(payment_id)
-
-    # Fail on validation errors
-    fail!(reason: "Payment amount must be positive") unless context.payment.amount > 0
-
-    # Fail on business rule violations
-    fail!(reason: "Insufficient funds", code: "INSUFFICIENT_FUNDS") unless sufficient_funds?
-
-    # Continue with processing
-    charge_payment
+class ProcessRefund < CMDx::Task
+  def work
+    # Without a reason
+    fail! if Array(ENV["DISABLED_TASKS"]).include?(self.class.name)
+
+    refund = Refund.find(context.refund_id)
+
+    # With a reason
+    if refund.expired?
+      fail!("Refund period has expired")
+    elsif !refund.amount.positive?
+      fail!("Refund amount must be positive")
+    else
+      refund.process!
+    end
   end
+end
 
-  private
+result = ProcessRefund.execute(refund_id: 789)
 
-  def sufficient_funds?
-    context.payment.account.balance >= context.payment.amount
-  end
-end
-```
+# Executed
+result.status #=> "failed"
 
-### Common Fail Scenarios
+# Without a reason
+result.reason #=> "no reason given"
 
-| Scenario | Example |
-|----------|---------|
-| **Validation errors** | `fail!(reason: "Invalid email format")` |
-| **Business rule violations** | `fail!(reason: "Credit limit exceeded")` |
-| **External service errors** | `fail!(reason: "Payment gateway unavailable")` |
-| **Data integrity issues** | `fail!(reason: "Duplicate transaction detected")` |
+# With a reason
+result.reason #=> "Refund period has expired"
+```
 
 ## Metadata Enrichment
 
-Both halt methods accept metadata to provide context about the interruption. Metadata is stored as a hash and becomes available through the result object.
-
-### Structured Metadata
+Both halt methods accept metadata to provide additional context about the interruption. Metadata is stored as a hash and becomes available through the result object.
 
 ```ruby
-class ProcessSubscriptionTask < CMDx::Task
-  required :user_id, type: :integer
-
-  def call
-    context.user = User.find(user_id)
-
-    if context.user.subscription_expired?
-      skip!(
-        reason: "Subscription expired",
-        user_id: context.user.id,
-        expired_at: context.user.subscription_expires_at,
-        plan_type: context.user.subscription_plan,
-        grace_period_ends: context.user.subscription_expires_at + 7.days
-      )
+class ProcessRenewal < CMDx::Task
+  def work
+    license = License.find(context.license_id)
+
+    if license.already_renewed?
+      # Without metadata
+      skip!("License already renewed")
     end
 
-    unless context.user.payment_method_valid?
+    unless license.renewal_eligible?
+      # With metadata
       fail!(
-        reason: "Invalid payment method",
-        user_id: context.user.id,
-        payment_method_id: context.user.payment_method&.id,
-        error_code: "PAYMENT_METHOD_INVALID",
-        retry_after: Time.current + 1.hour
+        "License not eligible for renewal",
+        error_code: "LICENSE.NOT_ELIGIBLE",
+        retry_after: Time.current + 30.days
       )
     end
 
-    process_subscription
+    process_renewal
   end
 end
-```
 
-### Accessing Metadata
+result = ProcessRenewal.execute(license_id: 567)
 
-```ruby
-result = ProcessSubscriptionTask.call(user_id: 123)
-
-# Check result status
-result.skipped?                         #=> true
-result.failed?                          #=> false
+# Without metadata
+result.metadata #=> {}
 
-# Access metadata
-result.metadata[:reason]                #=> "Subscription expired"
-result.metadata[:user_id]               #=> 123
-result.metadata[:expired_at]            #=> 2023-01-01 10:00:00 UTC
-result.metadata[:grace_period_ends]     #=> 2023-01-08 10:00:00 UTC
+# With metadata
+result.metadata #=> {
+                #     error_code: "LICENSE.NOT_ELIGIBLE",
+                #     retry_after: <Time 30 days from now>
+                #   }
 ```
 
 ## State Transitions
 
 Halt methods trigger specific state and status transitions:
 
-| Method | State Transition | Status | Outcome |
-|--------|------------------|--------|---------|
-| `skip!` | `executing` → `interrupted` | `skipped` | `good? = true`, `bad? = true` |
-| `fail!` | `executing` → `interrupted` | `failed` | `good? = false`, `bad? = true` |
+| Method | State | Status | Outcome |
+|--------|-------|--------|---------|
+| `skip!` | `interrupted` | `skipped` | `good? = true`, `bad? = true` |
+| `fail!` | `interrupted` | `failed` | `good? = false`, `bad? = true` |
 
 ```ruby
-result = ProcessSubscriptionTask.call(user_id: 123)
+result = ProcessRenewal.execute(license_id: 567)
 
 # State information
 result.state        #=> "interrupted"
@@ -191,96 +148,62 @@ result.good?        #=> true for skipped, false for failed
 result.bad?         #=> true for both skipped and failed
 ```
 
-## Exception Behavior
+## Execution Behavior
 
 Halt methods behave differently depending on the call method used:
 
-### With `call` (Non-bang)
+### Non-bang execution
 
-Returns a result object without raising exceptions:
+Returns result object without raising exceptions:
 
 ```ruby
-result = ProcessPaymentTask.call(payment_id: 123)
+result = ProcessRefund.execute(refund_id: 789)
 
 case result.status
 when "success"
-  puts "Payment processed: $#{result.context.payment.amount}"
+  puts "Refund processed: $#{result.context.refund.amount}"
 when "skipped"
-  puts "Payment skipped: #{result.metadata[:reason]}"
+  puts "Refund skipped: #{result.reason}"
 when "failed"
-  puts "Payment failed: #{result.metadata[:reason]}"
-  handle_payment_error(result.metadata[:code])
+  puts "Refund failed: #{result.reason}"
+  handle_refund_error(result.metadata[:error_code])
 end
 ```
 
-### With `call!` (Bang)
+### Bang execution
 
-> [!WARNING]
-> The `call!` method raises exceptions for halt conditions based on the `task_halt` configuration. Handle these exceptions appropriately in your application flow.
+Raises exceptions for halt conditions based on `task_breakpoints` configuration:
 
 ```ruby
 begin
-  result = ProcessPaymentTask.call!(payment_id: 123)
-  puts "Success: Payment processed for $#{result.context.payment.amount}"
-rescue CMDx::Skipped => e
+  result = ProcessRefund.execute!(refund_id: 789)
+  puts "Success: Refund processed"
+rescue CMDx::SkipFault => e
   puts "Skipped: #{e.message}"
-  log_skip_event(e.context.payment_id, e.result.metadata)
-rescue CMDx::Failed => e
+rescue CMDx::FailFault => e
   puts "Failed: #{e.message}"
-  handle_payment_failure(e.result.metadata[:code])
-  notify_payment_team(e.context.payment_id)
+  handle_refund_failure(e.result.metadata[:error_code])
 end
 ```
 
-## Error Handling
+## Best Practices
 
-### Invalid Metadata
-
-```ruby
-class ProcessOrderTask < CMDx::Task
-  def call
-    # This works - metadata accepts any hash
-    skip!(reason: "Valid skip", order_id: 123, custom_data: {nested: true})
-
-    # This also works - no metadata required
-    fail!
-  end
-end
-```
-
-## The Reason Key
-
-> [!TIP]
-> Always include a `:reason` key in metadata when using halt methods. This provides clear context for debugging and creates meaningful exception messages.
-
-The `:reason` key in metadata has special significance:
-
-- Used as the exception message when faults are raised
-- Provides human-readable explanation of the halt
-- Strongly recommended for all halt calls
+Always try to provide a `reason` when using halt methods. This provides clear context for debugging and creates meaningful exception messages.
 
 ```ruby
 # Good: Clear, specific reason
-skip!(reason: "User account suspended until manual review")
-fail!(reason: "Credit card declined by issuer", code: "CARD_DECLINED")
+skip!("Document processing paused for compliance review")
+fail!("File format not supported by processor", code: "FORMAT_UNSUPPORTED")
 
-# Acceptable: Other metadata without reason
-skip!(status: "redundant", processed_at: Time.current)
+# Acceptable: Generic, non-specific reason
+skip!("Paused")
+fail!("Unsupported")
 
-# Fallback: Default message if no reason provided
-skip! # Exception message: "no reason given"
-fail! # Exception message: "no reason given"
+# Bad: Default, cannot determine reason
+skip! #=> "no reason given"
+fail! #=> "no reason given"
 ```
 
-### Reason Best Practices
-
-| Practice | Example |
-|----------|---------|
-| **Be specific** | `"Credit card expired on 2023-12-31"` vs `"Payment error"` |
-| **Include context** | `"Inventory insufficient: need 5, have 2"` |
-| **Use actionable language** | `"Email verification required before login"` |
-| **Avoid technical jargon** | `"Payment declined"` vs `"Gateway returned 402"` |
-
 ---
 
 - **Prev:** [Basics - Chain](../basics/chain.md)