cmdx 1.0.1 → 1.1.1

data/lib/cmdx/fault.rb

@@ -1,109 +1,31 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Fault serves as the base exception class for task execution interruptions in CMDx.
-  # It provides a structured way to halt task execution with specific reasons and metadata,
-  # while offering advanced exception matching capabilities for precise error handling.
+  # Base fault class for handling task execution failures and interruptions.
   #
-  # Faults are automatically raised when using the bang `call!` method on tasks that
-  # encounter `skip!` or `fail!` conditions. They carry the full context of the
-  # interrupted task, including the result object with its metadata and execution state.
-  #
-  #
-  # ## Fault Types
-  #
-  # CMDx provides two primary fault types:
-  # - **CMDx::Skipped**: Raised when a task is skipped via `skip!`
-  # - **CMDx::Failed**: Raised when a task fails via `fail!`
-  #
-  # ## Exception Handling Patterns
-  #
-  # Faults support multiple rescue patterns for flexible error handling:
-  # - Standard rescue by fault type
-  # - Task-specific matching with `for?`
-  # - Custom matching with `matches?`
-  #
-  # @example Basic fault handling
-  #   begin
-  #     ProcessOrderTask.call!(order_id: 123)
-  #   rescue CMDx::Skipped => e
-  #     logger.info "Task skipped: #{e.message}"
-  #     e.result.metadata[:reason] #=> "Order already processed"
-  #   rescue CMDx::Failed => e
-  #     logger.error "Task failed: #{e.message}"
-  #     e.task.class.name #=> "ProcessOrderTask"
-  #   end
-  #
-  # @example Task-specific fault handling
-  #   begin
-  #     OrderProcessingWorkflow.call!(orders: orders)
-  #   rescue CMDx::Fault.for?(ProcessOrderTask, ValidateOrderTask) => e
-  #     # Handle faults only from specific task types
-  #     retry_order_processing(e.context.order_id)
-  #   end
-  #
-  # @example Advanced fault matching
-  #   begin
-  #     ProcessOrderTask.call!(order_id: 123)
-  #   rescue CMDx::Fault.matches? { |f| f.result.metadata[:code] == "INVENTORY_DEPLETED" } => e
-  #     # Handle specific fault conditions
-  #     schedule_restock_notification(e.context.order)
-  #   end
-  #
-  # @example Accessing fault context
-  #   begin
-  #     ProcessOrderTask.call!(order_id: 123)
-  #   rescue CMDx::Fault => e
-  #     e.result.status           #=> "failed" or "skipped"
-  #     e.result.metadata[:reason] #=> "Insufficient inventory"
-  #     e.task.id                 #=> Task instance UUID
-  #     e.context.order_id        #=> 123
-  #     e.chain.id                  #=> Chain instance UUID
-  #   end
-  #
-  # @example Fault propagation with throw!
-  #   class ProcessOrderTask < CMDx::Task
-  #     def call
-  #       validation_result = ValidateOrderTask.call(context)
-  #       throw!(validation_result) if validation_result.failed?
-  #
-  #       # This will raise CMDx::Failed with validation task's metadata
-  #     end
-  #   end
-  #
-  # @see Result Result object containing fault details
-  # @see Task Task execution methods (call vs call!)
-  # @see CMDx::Skipped Specific fault type for skipped tasks
-  # @see CMDx::Failed Specific fault type for failed tasks
-  # @since 1.0.0
+  # Faults are exceptions raised when tasks encounter specific execution states
+  # that prevent normal completion. Unlike regular exceptions, faults carry
+  # rich context information including the task result, execution chain, and
+  # contextual data that led to the fault condition. Faults can be caught and
+  # handled based on specific task types or custom matching criteria.
   class Fault < Error
 
-    __cmdx_attr_delegator :task, :chain, :context,
-                          to: :result
+    cmdx_attr_delegator :task, :chain, :context,
+                        to: :result
 
-    ##
-    # @!attribute [r] result
-    #   @return [Result] the result object that caused this fault
+    # @return [CMDx::Result] the result object that caused this fault
     attr_reader :result
 
-    ##
-    # Initializes a new Fault with the given result object.
-    # The fault message is derived from the result's metadata reason or falls back
-    # to a localized default message.
+    # Creates a new fault instance from a task execution result.
     #
-    # @param result [Result] the result object containing fault details
+    # @param result [CMDx::Result] the task result that caused the fault
     #
-    # @example Creating a fault from a failed result
-    #   result = ProcessOrderTask.call(order_id: 999) # Non-existent order
-    #   fault = Fault.new(result)
-    #   fault.message #=> "Order not found"
-    #   fault.result  #=> <Result status: "failed">
+    # @return [CMDx::Fault] the newly created fault instance
     #
-    # @example Fault with I18n message
-    #   # With custom locale configuration
-    #   fault = Fault.new(result)
-    #   fault.message #=> Localized message from I18n
+    # @example Create fault from failed task result
+    #   result = SomeTask.call(invalid_data: true)
+    #   fault = CMDx::Fault.new(result)
+    #   fault.task #=> SomeTask instance
     def initialize(result)
       @result = result
       super(result.metadata[:reason] || I18n.t("cmdx.faults.unspecified", default: "no reason given"))
@@ -111,52 +33,56 @@ module CMDx
 
     class << self
 
-      ##
       # Builds a specific fault type based on the result's status.
-      # Dynamically creates the appropriate fault subclass (Skipped, Failed, etc.)
-      # based on the result's current status.
       #
-      # @param result [Result] the result object to build a fault from
-      # @return [Fault] a fault instance of the appropriate subclass
+      # Creates an instance of the appropriate fault subclass (Skipped, Failed, etc.)
+      # by capitalizing the result status and looking up the corresponding fault class.
+      # This provides dynamic fault creation based on task execution outcomes.
       #
-      # @example Building a skipped fault
-      #   result = MyTask.call(param: "value")
-      #   result.skip!(reason: "Not needed")
-      #   fault = Fault.build(result)
+      # @param result [CMDx::Result] the task result to build a fault from
+      #
+      # @return [CMDx::Fault] an instance of the appropriate fault subclass
+      #
+      # @raise [NameError] if no fault class exists for the result status
+      #
+      # @example Build fault from skipped task result
+      #   result = SomeTask.call # result.status is :skipped
+      #   fault = CMDx::Fault.build(result)
       #   fault.class #=> CMDx::Skipped
       #
-      # @example Building a failed fault
-      #   result = MyTask.call(param: "invalid")
-      #   result.fail!(reason: "Validation error")
-      #   fault = Fault.build(result)
+      # @example Build fault from failed task result
+      #   result = SomeTask.call # result.status is :failed
+      #   fault = CMDx::Fault.build(result)
       #   fault.class #=> CMDx::Failed
       def build(result)
         fault = CMDx.const_get(result.status.capitalize)
         fault.new(result)
       end
 
-      ##
-      # Creates a fault matcher that only matches faults from specific task classes.
-      # This enables precise exception handling based on the task type that caused the fault.
+      # Creates a fault matcher that matches faults from specific task classes.
       #
-      # @param tasks [Array<Class>] task classes to match against
-      # @return [Class] a temporary fault class with custom matching logic
+      # Returns a dynamically created fault class that can be used in rescue blocks
+      # to catch faults only when they originate from specific task types. This enables
+      # selective fault handling based on the task that generated the fault.
       #
-      # @example Matching specific task types
+      # @param tasks [Array<Class>] one or more task classes to match against
+      #
+      # @return [Class] a fault matcher class that responds to case equality
+      #
+      # @example Catch faults from specific task types
       #   begin
-      #     OrderWorkflow.call!(orders: orders)
-      #   rescue CMDx::Fault.for?(ProcessOrderTask, ValidateOrderTask) => e
-      #     # Only handle faults from these specific task types
-      #     handle_order_processing_error(e)
+      #     PaymentTask.call!
+      #   rescue CMDx::Fault.for?(PaymentTask, RefundTask) => e
+      #     puts "Payment operation failed: #{e.message}"
       #   end
       #
-      # @example Multiple task matching
-      #   payment_tasks = [ProcessPaymentTask, ValidateCardTask, ChargeCardTask]
+      # @example Match faults from multiple task types
+      #   UserTaskFaults = CMDx::Fault.for?(CreateUserTask, UpdateUserTask, DeleteUserTask)
+      #
       #   begin
-      #     PaymentWorkflow.call!(payment_data: data)
-      #   rescue CMDx::Failed.for?(*payment_tasks) => e
-      #     # Handle failures from any payment-related task
-      #     process_payment_failure(e)
+      #     workflow.call!
+      #   rescue CMDx::Fault.for?(CreateUserTask, UpdateUserTask, DeleteUserTask) => e
+      #     handle_user_operation_failure(e)
       #   end
       def for?(*tasks)
         temp_fault = Class.new(self) do
@@ -168,41 +94,33 @@ module CMDx
         temp_fault.tap { |c| c.instance_variable_set(:@tasks, tasks) }
       end
 
-      ##
-      # Creates a fault matcher with custom matching logic via a block.
-      # This enables sophisticated fault matching based on any aspect of the fault,
-      # including result metadata, task state, or context values.
+      # Creates a fault matcher using a custom block for matching criteria.
+      #
+      # Returns a dynamically created fault class that uses the provided block
+      # to determine if a fault should be matched. The block receives the fault
+      # instance and should return true if the fault matches the desired criteria.
+      # This enables custom fault handling logic beyond simple task type matching.
+      #
+      # @param block [Proc] a block that receives a fault and returns boolean
+      #
+      # @return [Class] a fault matcher class that responds to case equality
       #
-      # @param block [Proc] block that receives the fault and returns true/false for matching
-      # @return [Class] a temporary fault class with custom matching logic
       # @raise [ArgumentError] if no block is provided
       #
-      # @example Matching by error code
+      # @example Match faults by custom criteria
       #   begin
-      #     ProcessOrderTask.call!(order_id: 123)
-      #   rescue CMDx::Fault.matches? { |f| f.result.metadata[:error_code] == "PAYMENT_DECLINED" } => e
-      #     # Handle specific payment errors
-      #     retry_with_different_payment_method(e.context)
+      #     LongRunningTask.call!
+      #   rescue CMDx::Fault.matches? { |fault| fault.context[:timeout_exceeded] } => e
+      #     puts "Task timed out: #{e.message}"
       #   end
       #
-      # @example Matching by context values
-      #   begin
-      #     ProcessOrderTask.call!(order_id: 123)
-      #   rescue CMDx::Fault.matches? { |f| f.context.order_value > 1000 } => e
-      #     # Handle high-value order failures differently
-      #     escalate_to_manager(e)
-      #   end
+      # @example Match faults by metadata content
+      #   ValidationFault = CMDx::Fault.matches? { |fault| fault.result.metadata[:type] == "validation_error" }
       #
-      # @example Complex matching logic
       #   begin
-      #     WorkflowProcessor.call!(items: items)
-      #   rescue CMDx::Fault.matches? { |f|
-      #     f.result.failed? &&
-      #     f.result.metadata[:reason]&.include?("timeout") &&
-      #     f.chain.results.count(&:failed?) < 3
-      #   } => e
-      #     # Retry if it's a timeout with fewer than 3 failures in the chain
-      #     retry_with_longer_timeout(e)
+      #     ValidateUserTask.call!
+      #   rescue ValidationFault => e
+      #     display_validation_errors(e.result.errors)
       #   end
       def matches?(&block)
         raise ArgumentError, "block required" unless block_given?

data/lib/cmdx/faults.rb

@@ -2,166 +2,55 @@
 
 module CMDx
 
-  ##
-  # Skipped is a specific fault type raised when a task execution is intentionally
-  # skipped via the `skip!` method. This represents a controlled interruption where
-  # the task determines that execution is not necessary or appropriate under the
-  # current conditions.
+  # Fault raised when a task is intentionally skipped during execution.
   #
-  # Skipped faults are typically used for:
-  # - Conditional logic where certain conditions make execution unnecessary
-  # - Early returns when prerequisites are not met
-  # - Business logic that determines the operation is redundant
-  # - Graceful handling of edge cases that don't constitute errors
-  #
-  # @example Basic skip usage
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
+  # This fault occurs when a task determines it should not execute based on
+  # its current context or conditions. Skipped tasks are not considered failures
+  # but rather intentional bypasses of task execution logic.
   #
+  # @example Task that skips based on conditions
+  #   class ProcessPaymentTask < CMDx::Task
   #     def call
-  #       context.order = Order.find(order_id)
-  #       skip!(reason: "Order already processed") if context.order.processed?
-  #
-  #       context.order.process!
+  #       skip!(reason: "Payment already processed") if payment_exists?
   #     end
   #   end
   #
-  #   # Non-bang call returns result
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.skipped? #=> true
-  #   result.metadata[:reason] #=> "Order already processed"
+  #   result = ProcessPaymentTask.call(payment_id: 123)
+  #   # raises CMDx::Skipped when payment already exists
   #
-  #   # Bang call raises exception
+  # @example Catching skipped faults
   #   begin
-  #     ProcessOrderTask.call!(order_id: 123)
+  #     MyTask.call!(data: "invalid")
   #   rescue CMDx::Skipped => e
-  #     puts "Skipped: #{e.message}"
-  #   end
-  #
-  # @example Conditional skip logic
-  #   class SendNotificationTask < CMDx::Task
-  #     required :user_id, type: :integer
-  #     optional :force, type: :boolean, default: false
-  #
-  #     def call
-  #       context.user = User.find(user_id)
-  #
-  #       unless force || context.user.notifications_enabled?
-  #         skip!(reason: "User has notifications disabled")
-  #       end
-  #
-  #       NotificationService.send(context.user)
-  #     end
+  #     puts "Task was skipped: #{e.message}"
   #   end
-  #
-  # @example Handling skipped tasks in workflows
-  #   begin
-  #     OrderProcessingWorkflow.call!(orders: orders)
-  #   rescue CMDx::Skipped => e
-  #     # Log skipped operations but continue processing
-  #     logger.info "Skipped processing: #{e.message}"
-  #   end
-  #
-  # @see Fault Base fault class with advanced matching capabilities
-  # @see Failed Failed fault type for error conditions
-  # @see Result#skip! Method for triggering skipped faults
-  # @since 1.0.0
   Skipped = Class.new(Fault)
 
-  ##
-  # Failed is a specific fault type raised when a task execution encounters an
-  # error condition via the `fail!` method. This represents a controlled failure
-  # where the task explicitly determines that execution cannot continue successfully.
+  # Fault raised when a task execution fails due to errors or validation failures.
   #
-  # Failed faults are typically used for:
-  # - Validation errors that prevent successful execution
-  # - Business rule violations that constitute failures
-  # - Resource unavailability or constraint violations
-  # - Explicit error conditions that require attention
-  #
-  # @example Basic failure usage
-  #   class ProcessPaymentTask < CMDx::Task
-  #     required :payment_amount, type: :float
-  #     required :payment_method, type: :string
-  #
-  #     def call
-  #       unless payment_amount > 0
-  #         fail!(reason: "Payment amount must be positive", code: "INVALID_AMOUNT")
-  #       end
+  # This fault occurs when a task encounters an error condition, validation failure,
+  # or any other condition that prevents successful completion. Failed tasks indicate
+  # that the intended operation could not be completed successfully.
   #
-  #       unless valid_payment_method?
-  #         fail!(reason: "Invalid payment method", code: "INVALID_METHOD")
-  #       end
-  #
-  #       process_payment
-  #     end
-  #   end
-  #
-  #   # Non-bang call returns result
-  #   result = ProcessPaymentTask.call(payment_amount: -10, payment_method: "card")
-  #   result.failed? #=> true
-  #   result.metadata[:reason] #=> "Payment amount must be positive"
-  #   result.metadata[:code] #=> "INVALID_AMOUNT"
-  #
-  #   # Bang call raises exception
-  #   begin
-  #     ProcessPaymentTask.call!(payment_amount: -10, payment_method: "card")
-  #   rescue CMDx::Failed => e
-  #     puts "Failed: #{e.message}"
-  #     puts "Error code: #{e.result.metadata[:code]}"
-  #   end
-  #
-  # @example Validation failure with detailed metadata
-  #   class CreateUserTask < CMDx::Task
+  # @example Task that fails due to validation
+  #   class ValidateUserTask < CMDx::Task
   #     required :email, type: :string
-  #     required :password, type: :string
   #
   #     def call
-  #       if User.exists?(email: email)
-  #         fail!(
-  #           "Email already exists",
-  #           code: "EMAIL_EXISTS",
-  #           field: "email",
-  #           suggested_action: "Use different email or login instead"
-  #         )
-  #       end
-  #
-  #       context.user = User.create!(email: email, password: password)
+  #       fail!(reason: "Invalid email format") unless valid_email?
   #     end
   #   end
   #
-  # @example Handling specific failure types
+  #   result = ValidateUserTask.call(email: "invalid-email")
+  #   # raises CMDx::Failed when email is invalid
+  #
+  # @example Catching failed faults
   #   begin
-  #     ProcessOrderTask.call!(order_id: 123)
-  #   rescue CMDx::Failed.matches? { |f| f.result.metadata[:code] == "PAYMENT_DECLINED" } => e
-  #     # Handle payment failures specifically
-  #     retry_with_backup_payment_method(e.context)
+  #     RiskyTask.call!(data: "problematic")
   #   rescue CMDx::Failed => e
-  #     # Handle all other failures
-  #     log_failure_and_notify_support(e)
+  #     puts "Task failed: #{e.message}"
+  #     puts "Original task: #{e.task.class.name}"
   #   end
-  #
-  # @example Failure propagation in complex workflows
-  #   class OrderFulfillmentTask < CMDx::Task
-  #     def call
-  #       payment_result = ProcessPaymentTask.call(context)
-  #
-  #       if payment_result.failed?
-  #         fail!(
-  #           "Cannot fulfill order due to payment failure",
-  #           code: "PAYMENT_REQUIRED",
-  #           original_error: payment_result.metadata
-  #         )
-  #       end
-  #
-  #       fulfill_order
-  #     end
-  #   end
-  #
-  # @see Fault Base fault class with advanced matching capabilities
-  # @see Skipped Skipped fault type for conditional interruptions
-  # @see Result#fail! Method for triggering failed faults
-  # @since 1.0.0
   Failed = Class.new(Fault)
 
 end

data/lib/cmdx/immutator.rb

@@ -1,126 +1,38 @@
 # frozen_string_literal: true
 
 module CMDx
-  ##
-  # Immutator provides task finalization by freezing objects to prevent mutation
-  # after task execution is complete. This ensures task immutability and prevents
-  # accidental side effects or modifications to completed task instances.
+  # Provides object immutability functionality for tasks and their associated objects.
   #
-  # The Immutator is automatically called during the task termination phase as part
-  # of the execution lifecycle. It freezes the task instance, its result, and
-  # associated objects to maintain data integrity and enforce the single-use pattern
-  # of CMDx tasks.
-  #
-  # ## Freezing Strategy
-  #
-  # The Immutator employs a selective freezing strategy:
-  # 1. **Task Instance**: Always frozen to prevent method calls and modifications
-  # 2. **Result Object**: Always frozen to preserve execution outcome
-  # 3. **Context Object**: Frozen only for the first task in a chain (index 0)
-  # 4. **Chain Object**: Frozen only for the first task in a chain (index 0)
-  #
-  # This selective approach allows subsequent tasks in a workflow or chain to continue
-  # using the shared context and chain objects while ensuring completed tasks remain
-  # immutable.
-  #
-  # ## Test Environment Handling
-  #
-  # In test environments (Rails or Rack), freezing is automatically disabled to
-  # prevent conflicts with test frameworks that may need to stub or mock frozen
-  # objects. This ensures smooth testing without compromising the immutability
-  # guarantees in production environments.
-  #
-  # @example Task execution with automatic freezing
-  #   class ProcessOrderTask < CMDx::Task
-  #     required :order_id, type: :integer
-  #
-  #     def call
-  #       context.order = Order.find(order_id)
-  #       context.order.process!
-  #     end
-  #   end
-  #
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.frozen?         #=> true
-  #   result.task.frozen?    #=> true
-  #   result.context.frozen? #=> true (if first task in chain)
-  #
-  # @example Attempting to modify frozen task (will raise error)
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.context.new_field = "value"  #=> FrozenError
-  #   result.task.call                    #=> FrozenError
-  #
-  # @example Workflow execution with selective freezing
-  #   class OrderWorkflow < CMDx::Workflow
-  #     def call
-  #       ProcessOrderTask.call(context)
-  #       SendEmailTask.call(context)
-  #     end
-  #   end
-  #
-  #   result = OrderWorkflow.call(order_id: 123)
-  #   # First task freezes context and chain
-  #   # Second task can still use unfrozen context for execution
-  #   # But both task instances are individually frozen
-  #
-  # @example Test environment behavior
-  #   # In test environment (SKIP_CMDX_FREEZING=1)
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.frozen?      #=> false (freezing disabled)
-  #   result.task.frozen? #=> false (allows stubbing/mocking)
-  #
-  # @see Task Task execution lifecycle
-  # @see Result Result object that gets frozen
-  # @see Context Context object that may get frozen
-  # @see Chain Chain object that may get frozen
-  # @since 1.0.0
+  # This module freezes task objects and their related components after execution
+  # to prevent unintended modifications. It supports conditional freezing through
+  # environment variable configuration, allowing developers to disable immutability
+  # during testing scenarios where object stubbing is required.
   module Immutator
 
     module_function
 
-    ##
-    # Freezes task-related objects to ensure immutability after execution.
-    # This method is called automatically during task termination and implements
-    # a selective freezing strategy based on task position within a chain.
-    #
-    # The freezing process:
-    # 1. Checks if running in test environment and skips freezing if so
-    # 2. Always freezes the task instance and its result
-    # 3. Freezes context and chain only for the first task (index 0) in a chain
-    #
-    # This selective approach ensures that:
-    # - Completed tasks cannot be modified or re-executed
-    # - Results remain immutable and trustworthy
-    # - Shared objects (context/chain) remain available for subsequent tasks
-    # - Test environments can continue to function with mocking/stubbing
-    #
-    # @param task [Task] the task instance to freeze along with its associated objects
-    # @return [void]
+    # Freezes a task and its associated objects to prevent further modification.
     #
-    # @example First task in chain (freezes everything)
-    #   task = ProcessOrderTask.call(order_id: 123)
-    #   # task.result.index == 0
-    #   Immutator.call(task)
-    #   # Freezes: task, result, context, chain
+    # This method makes the task, its result, and related objects immutable after
+    # execution. If the task result index is zero (indicating the first task in a chain),
+    # it also freezes the context and chain objects. The freezing behavior can be
+    # disabled via the SKIP_CMDX_FREEZING environment variable for testing purposes.
     #
-    # @example Subsequent task in chain (selective freezing)
-    #   # After first task has run
-    #   task = SendEmailTask.call(context)
-    #   # task.result.index == 1
-    #   Immutator.call(task)
-    #   # Freezes: task, result (context and chain remain unfrozen)
+    # @param task [CMDx::Task] the task instance to freeze along with its associated objects
     #
-    # @example Test environment (no freezing)
-    #   ENV["RAILS_ENV"] = "test"
-    #   task = ProcessOrderTask.call(order_id: 123)
-    #   Immutator.call(task)
-    #   # No objects are frozen, allows test stubbing
+    # @return [void] returns nil when freezing is skipped, otherwise no meaningful return value
     #
-    # @note This method is automatically called by the task execution framework
-    #   and should not typically be called directly by user code.
+    # @example Freeze a task after execution
+    #   task = MyTask.call(user_id: 123)
+    #   CMDx::Immutator.call(task)
+    #   task.frozen? #=> true
+    #   task.result.frozen? #=> true
     #
-    # @note Freezing is skipped entirely in test environments to prevent conflicts
-    #   with test frameworks that need to stub or mock objects.
+    # @example Skip freezing during testing
+    #   ENV["SKIP_CMDX_FREEZING"] = "true"
+    #   task = MyTask.call(user_id: 123)
+    #   CMDx::Immutator.call(task)
+    #   task.frozen? #=> false
     def call(task)
       # Stubbing on frozen objects is not allowed
       skip_freezing = ENV.fetch("SKIP_CMDX_FREEZING", false)