cmdx 1.1.2 → 1.5.0

data/docs/workflows.md

@@ -1,374 +1,190 @@
-# Workflow
+# Workflows
 
-CMDx::Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business workflows from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
-
-Workflows inherit from Task, gaining all task capabilities including callbacks, parameter validation, result tracking, and configuration. The key difference is that workflows coordinate other tasks rather than implementing business logic directly.
+Workflow orchestrates sequential execution of multiple tasks in a linear pipeline. Workflows provide a declarative DSL for composing complex business logic from individual task components, with support for conditional execution, context propagation, and configurable halt behavior.
 
 ## Table of Contents
 
-- [TLDR](#tldr)
-- [Basic Usage](#basic-usage)
-- [Task Declaration](#task-declaration)
-- [Context Propagation](#context-propagation)
-- [Conditional Execution](#conditional-execution)
+- [Declarations](#declarations)
+  - [Task](#task)
+  - [Group](#group)
+  - [Conditionals](#conditionals)
 - [Halt Behavior](#halt-behavior)
-  - [Default Behavior](#default-behavior)
-  - [Class-Level Configuration](#class-level-configuration)
-  - [Group-Level Configuration](#group-level-configuration)
-  - [Available Result Statuses](#available-result-statuses)
-- [Process Method Options](#process-method-options)
-- [Error Handling](#error-handling)
+  - [Task Configuration](#task-configuration)
+  - [Group Configuration](#group-configuration)
 - [Nested Workflows](#nested-workflows)
-- [Task Settings Integration](#task-settings-integration)
-- [Generator](#generator)
-
-## TLDR
-
-```ruby
-# Basic workflow - sequential task execution
-class OrderWorkflow < CMDx::Workflow
-  process ValidateOrderTask      # Step 1
-  process CalculateTaxTask       # Step 2
-  process ChargePaymentTask      # Step 3
-end
 
-# Conditional execution
-process SendEmailTask, if: proc { context.notify_user? }
-process SkipableTask, unless: :should_skip?
+## Declarations
 
-# Halt behavior control
-process CriticalTask, workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
-process OptionalTask, workflow_halt: []  # Never halt
+Tasks execute in declaration order (FIFO). The workflow context propagates to each task, allowing access to data from previous executions.
 
-# Context flows through all tasks automatically
-result = OrderWorkflow.call(order: order)
-result.context.tax_amount    # Set by CalculateTaxTask
-result.context.payment_id    # Set by ChargePaymentTask
-```
-
-## Basic Usage
+> [!IMPORTANT]
+> Do **NOT** define a `work` method in workflow tasks. The included module automatically provides the execution logic.
 
-> [!WARNING]
-> Do **NOT** define a `call` method in workflow classes. The workflow automatically provides execution logic.
+### Task
 
 ```ruby
-class OrderProcessingWorkflow < CMDx::Workflow
-  process ValidateOrderTask
-  process CalculateTaxTask
-  process ChargePaymentTask
-  process FulfillOrderTask
-end
+class OnboardingWorkflow < CMDx::Task
+  include CMDx::Workflow
 
-# Execute workflow
-result = OrderProcessingWorkflow.call(order: order, user: current_user)
+  task CreateUserProfile
+  task SetupAccountPreferences
 
-if result.success?
-  redirect_to order_path(result.context.order)
-elsif result.failed?
-  handle_error(result.metadata[:reason])
+  tasks SendWelcomeEmail, SendWelcomeSms, CreateDashboard
 end
 ```
 
-## Task Declaration
+### Group
 
-Tasks are declared using the `process` method in execution order:
+Group related tasks for better organization and shared configuration:
+
+> [!IMPORTANT]
+> Settings and conditionals for a group apply to all tasks within that group.
 
 ```ruby
-class NotificationWorkflow < CMDx::Workflow
-  # Single task
-  process PrepareNotificationTask
+class ContentModerationWorkflow < CMDx::Task
+  include CMDx::Workflow
 
-  # Multiple tasks (grouped with same options)
-  process SendEmailTask, SendSmsTask, SendPushTask
+  # Screening phase
+  tasks ScanForProfanity, CheckForSpam, ValidateImages, breakpoints: ["skipped"]
 
-  # Tasks with conditions
-  process SendWebhookTask, if: proc { context.webhook_enabled? }
-  process SendSlackTask, unless: :slack_disabled?
+  # Review phase
+  tasks ApplyFilters, ScoreContent, FlagSuspicious
 
-  private
-
-  def slack_disabled?
-    !context.user.slack_enabled?
-  end
+  # Decision phase
+  tasks PublishContent, QueueForReview, NotifyModerators
 end
 ```
 
-> [!IMPORTANT]
-> Tasks execute in declaration order (FIFO). Use grouping to apply the same options to multiple tasks.
-
-## Context Propagation
+### Conditionals
 
-The context object flows through all tasks, creating a data pipeline:
+Conditionals support multiple syntaxes for flexible execution control:
 
 ```ruby
-class PaymentWorkflow < CMDx::Workflow
-  process ValidateOrderTask  # Sets context.validation_errors
-  process CalculateTaxTask   # Uses context.order, sets context.tax_amount
-  process ChargePaymentTask  # Uses context.tax_amount, sets context.payment_id
+class ContentAccessCheck
+  def call(task)
+    task.context.user.can?(:publish_content)
+  end
 end
 
-result = PaymentWorkflow.call(order: order)
-# Context contains cumulative data from all executed tasks
-result.context.validation_errors  # From ValidateOrderTask
-result.context.tax_amount         # From CalculateTaxTask
-result.context.payment_id         # From ChargePaymentTask
-```
-
-## Conditional Execution
+class OnboardingWorkflow < CMDx::Task
+  include CMDx::Workflow
 
-Tasks can execute conditionally using `:if` and `:unless` options:
+  # If and/or Unless
+  task SendWelcomeEmail, if: :email_configured?, unless: :email_disabled?
 
-```ruby
-class UserWorkflow < CMDx::Workflow
-  process ValidateUserTask
+  # Proc
+  task SendWelcomeEmail, if: ->(workflow) { Rails.env.production? && workflow.class.name.include?("Premium") }
 
-  # Proc condition
-  process UpgradeToPremiumTask, if: proc { context.user.premium? }
+  # Lambda
+  task SendWelcomeEmail, if: proc { |workflow| workflow.context.features_enabled? }
 
-  # Lambda condition
-  process ProcessInternationalTask, unless: -> { context.user.domestic? }
+  # Class or Module
+  task SendWelcomeEmail, unless: ContentAccessCheck
 
-  # Method condition
-  process LogDebugInfoTask, if: :debug_enabled?
+  # Instance
+  task SendWelcomeEmail, if: ContentAccessCheck.new
 
-  # Complex condition
-  process SendSpecialOfferTask, if: proc {
-    context.user.active? &&
-    context.feature_enabled?(:offers) &&
-    business_hours?
-  }
+  # Conditional applies to all tasks of this declaration group
+  tasks SendWelcomeEmail, CreateDashboard, SetupTutorial, if: :email_configured?
 
   private
 
-  def debug_enabled?
-    Rails.env.development?
+  def email_configured?
+    context.user.email_address.present?
   end
 
-  def business_hours?
-    Time.now.hour.between?(9, 17)
+  def email_disabled?
+    context.user.communication_preference == :disabled
   end
 end
 ```
 
-> [!NOTE]
-> Conditions are evaluated in the workflow instance context. Skipped tasks return `SKIPPED` status but don't halt execution by default.
-
 ## Halt Behavior
 
-Workflows control execution flow by halting on specific result statuses.
-
-### Default Behavior
-
-By default, workflows halt on `FAILED` status but continue on `SKIPPED`:
+By default skipped tasks are considered no-op executions and does not stop workflow execution.
+This is configurable via global and task level breakpoint settings. Task and group configurations
+can be used together within a workflow.
 
 ```ruby
-class DataWorkflow < CMDx::Workflow
-  process LoadDataTask      # If fails → workflow stops
-  process ValidateDataTask  # If skipped → workflow continues
-  process SaveDataTask      # Only runs if no failures occurred
+class AnalyticsWorkflow < CMDx::Task
+  include CMDx::Workflow
+
+  task CollectMetrics      # If fails → workflow stops
+  task FilterOutliers      # If skipped → workflow continues
+  task GenerateDashboard   # Only runs if no failures occurred
 end
 ```
 
-### Class-Level Configuration
+### Task Configuration
 
 Configure halt behavior for the entire workflow:
 
 ```ruby
-class CriticalWorkflow < CMDx::Workflow
+class SecurityWorkflow < CMDx::Task
+  include CMDx::Workflow
+
   # Halt on both failed and skipped results
-  cmd_settings!(workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED])
+  settings(workflow_breakpoints: ["skipped", "failed"])
 
-  process LoadCriticalDataTask
-  process ValidateCriticalDataTask
+  task PerformSecurityScan
+  task ValidateSecurityRules
 end
 
-class OptionalWorkflow < CMDx::Workflow
+class OptionalTasksWorkflow < CMDx::Task
+  include CMDx::Workflow
+
   # Never halt, always continue
-  cmd_settings!(workflow_halt: [])
+  settings(breakpoints: [])
 
-  process TryLoadDataTask
-  process TryValidateDataTask
-  process TrySaveDataTask
+  task TryBackupData
+  task TryCleanupLogs
+  task TryOptimizeCache
 end
 ```
 
-### Group-Level Configuration
+### Group Configuration
 
 Different task groups can have different halt behavior:
 
 ```ruby
-class AccountWorkflow < CMDx::Workflow
-  # Critical tasks - halt on any failure or skip
-  process CreateUserTask, ValidateUserTask,
-    workflow_halt: [CMDx::Result::FAILED, CMDx::Result::SKIPPED]
-
-  # Optional tasks - never halt
-  process SendWelcomeEmailTask, CreateProfileTask,
-    workflow_halt: []
-
-  # Default behavior for remaining tasks
-  process NotifyAdminTask, LogUserCreationTask
-end
-```
-
-### Available Result Statuses
-
-Use these statuses in `workflow_halt` arrays:
-
-| Status | Description |
-|--------|-------------|
-| `CMDx::Result::SUCCESS` | Task completed successfully |
-| `CMDx::Result::SKIPPED` | Task was skipped intentionally |
-| `CMDx::Result::FAILED` | Task failed due to error or validation |
-
-## Process Method Options
-
-The `process` method supports these options:
-
-| Option | Description | Example |
-|--------|-------------|---------|
-| `:if` | Execute task if condition is true | `if: proc { context.enabled? }` |
-| `:unless` | Execute task if condition is false | `unless: :should_skip?` |
-| `:workflow_halt` | Which statuses should halt execution | `workflow_halt: [CMDx::Result::FAILED]` |
-
-Conditions can be procs, lambdas, symbols, or strings referencing instance methods.
-
-## Error Handling
-
-> [!WARNING]
-> Workflow failures provide detailed information about which task failed and why, enabling precise error handling and debugging.
-
-```ruby
-class OrderWorkflow < CMDx::Workflow
-  process ValidateOrderTask
-  process CalculateTaxTask
-  process ChargePaymentTask
-end
-
-result = OrderWorkflow.call(order: invalid_order)
-
-if result.failed?
-  result.metadata
-  # {
-  #   reason: "ValidateOrderTask failed: Order ID is required",
-  #   failed_task: "ValidateOrderTask",
-  #   task_index: 0,
-  #   executed_tasks: ["ValidateOrderTask"],
-  #   skipped_tasks: [],
-  #   context_at_failure: { order: {...} }
-  # }
-end
-```
-
-### Common Error Scenarios
-
-```ruby
-# Task raises exception
-class ProcessDataWorkflow < CMDx::Workflow
-  process ValidateDataTask  # Raises validation error
-  process TransformDataTask # Never executes
-end
+class SubscriptionWorkflow < CMDx::Task
+  include CMDx::Workflow
 
-result = ProcessDataWorkflow.call(data: nil)
-result.failed?  # → true
-result.metadata[:reason]  # → "ValidateDataTask failed: Data cannot be nil"
+  task CreateSubscription, ValidatePayment, workflow_breakpoints: ["skipped", "failed"]
 
-# Halt on skipped task
-class StrictWorkflow < CMDx::Workflow
-  process RequiredTask, workflow_halt: [CMDx::Result::SKIPPED]
-  process OptionalTask, if: proc { false }  # Always skipped
-  process FinalTask  # Never executes
+  # Never halt, always continue
+  task SendConfirmationEmail, UpdateBilling, breakpoints: []
 end
-
-result = StrictWorkflow.call
-result.failed?  # → true (halted on skipped task)
 ```
 
-> [!TIP]
-> Use specific halt configurations to implement different failure strategies: strict validation, best-effort processing, or fault-tolerant pipelines.
-
 ## Nested Workflows
 
-Workflows can process other workflows for hierarchical composition:
+Workflows can task other workflows for hierarchical composition:
 
 ```ruby
-class DataPreProcessingWorkflow < CMDx::Workflow
-  process ValidateInputTask
-  process SanitizeDataTask
-end
-
-class DataProcessingWorkflow < CMDx::Workflow
-  process TransformDataTask
-  process ApplyBusinessLogicTask
-end
+class EmailPreparationWorkflow < CMDx::Task
+  include CMDx::Workflow
 
-class CompleteDataWorkflow < CMDx::Workflow
-  process DataPreProcessingWorkflow
-  process DataProcessingWorkflow, if: proc { context.pre_processing_successful? }
-  process GenerateReportTask
+  task ValidateRecipients
+  task CompileTemplate
 end
-```
-
-> [!NOTE]
-> Nested workflows share the same context object, enabling seamless data flow across workflow boundaries.
-
-## Task Settings Integration
-
-Workflows support all task capabilities including parameters, callbacks, and configuration:
-
-```ruby
-class PaymentWorkflow < CMDx::Workflow
-  # Parameter validation
-  required :order_id, type: :integer
-  optional :notify_user, type: :boolean, default: true
-
-  # Workflow settings
-  cmd_settings!(
-    workflow_halt: [CMDx::Result::FAILED],
-    log_level: :debug,
-    tags: [:critical, :payment]
-  )
-
-  # Callbacks
-  before_execution :setup_context
-  after_execution :cleanup_resources
-
-  process ValidateOrderTask
-  process ProcessPaymentTask
-  process NotifyUserTask, if: proc { context.notify_user }
-
-  private
 
-  def setup_context
-    context.start_time = Time.now
-  end
+class EmailDeliveryWorkflow < CMDx::Task
+  include CMDx::Workflow
 
-  def cleanup_resources
-    context.temp_files&.each(&:delete)
-  end
+  tasks SendEmails, TrackDeliveries
 end
-```
 
-## Generator
+class CompleteEmailWorkflow < CMDx::Task
+  include CMDx::Workflow
 
-Generate workflow scaffolding using the Rails generator:
-
-```bash
-rails g cmdx:workflow ProcessOrder
-```
-
-Creates `app/commands/process_order_workflow.rb`:
-
-```ruby
-class ProcessOrderWorkflow < ApplicationWorkflow
-  process # TODO: Add your tasks here
+  task EmailPreparationWorkflow
+  task EmailDeliveryWorkflow, if: proc { context.preparation_successful? }
+  task GenerateDeliveryReport
 end
 ```
 
-> [!NOTE]
-> The generator creates workflow files in `app/commands/`, inherits from `ApplicationWorkflow` if available (otherwise `CMDx::Workflow`), and handles proper naming conventions.
-
 ---
 
-- **Prev:** [Middlewares](middlewares.md)
-- **Next:** [Logging](logging.md)
+- **Prev:** [Deprecation](deprecation.md)
+- **Next:** [Tips and Tricks](tips_and_tricks.md)