cmdx 1.0.1 → 1.1.1

data/lib/cmdx/result.rb

@@ -1,62 +1,54 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Result object representing the outcome of task execution.
+  # Represents the execution result of a task, tracking state, status, and metadata.
   #
-  # The Result class encapsulates all information about a task's execution,
-  # including its state, status, metadata, and runtime information. It provides
-  # a comprehensive interface for tracking task lifecycle, handling failures,
-  # and chaining execution outcomes.
-  #
-  # @example Basic result usage
-  #   result = ProcessOrderTask.call(order_id: 123)
-  #   result.success?   # => true
-  #   result.complete?  # => true
-  #   result.runtime    # => 0.5
-  #
-  # @example Result with failure handling
-  #   result = ProcessOrderTask.call(invalid_params)
-  #   result.failed?    # => true
-  #   result.bad?       # => true
-  #   result.metadata   # => { reason: "Invalid parameters" }
-  #
-  # @example Result state callbacks
-  #   ProcessOrderTask.call(order_id: 123)
-  #     .on_success { |result| logger.info "Order processed successfully" }
-  #     .on_failed { |result| logger.error "Order processing failed: #{result.metadata[:reason]}" }
-  #
-  # @example Result chaining and failure propagation
-  #   result1 = FirstTask.call
-  #   result2 = SecondTask.call
-  #   result2.throw!(result1) if result1.failed?  # Propagate failure
-  #
-  # @see CMDx::Task Task execution and result creation
-  # @see CMDx::Chain Chain execution context and result tracking
-  # @see CMDx::Fault Fault handling for result failures
+  # Result objects encapsulate the outcome of task execution, providing detailed
+  # information about execution state (initialized, executing, complete, interrupted),
+  # status (success, skipped, failed), and associated metadata. They support
+  # state transitions, status changes, and provide introspection capabilities
+  # for debugging and monitoring task execution.
   class Result
 
-    __cmdx_attr_delegator :context, :chain,
-                          to: :task
+    STATES = [
+      INITIALIZED = "initialized",  # Initial state before execution
+      EXECUTING   = "executing",    # Currently executing task logic
+      COMPLETE    = "complete",     # Successfully completed execution
+      INTERRUPTED = "interrupted"   # Execution was halted due to failure
+    ].freeze
+    STATUSES = [
+      SUCCESS = "success",  # Task completed successfully
+      SKIPPED = "skipped",  # Task was skipped intentionally
+      FAILED  = "failed"    # Task failed due to error or validation
+    ].freeze
+
+    cmdx_attr_delegator :context, :chain,
+                        to: :task
 
     # @return [CMDx::Task] The task instance that generated this result
+    attr_reader :task
+
     # @return [String] The current execution state (initialized, executing, complete, interrupted)
+    attr_reader :state
+
     # @return [String] The current execution status (success, skipped, failed)
+    attr_reader :status
+
     # @return [Hash] Additional metadata associated with the result
-    attr_reader :task, :state, :status, :metadata
+    attr_reader :metadata
 
-    # Initializes a new Result instance.
+    # Initializes a new result for the given task
+    #
+    # @param task [CMDx::Task] the task to create a result for
     #
-    # Creates a result object for tracking task execution outcomes.
-    # Results start in initialized state with success status.
+    # @return [CMDx::Result] a new result instance
     #
-    # @param task [CMDx::Task] The task instance this result belongs to
-    # @raise [TypeError] If task is not a Task or Workflow instance
+    # @raise [TypeError] if task is not a Task or Workflow
     #
-    # @example Creating a result
-    #   task = ProcessOrderTask.new
-    #   result = Result.new(task)
-    #   result.initialized?  # => true
-    #   result.success?      # => true
+    # @example Create a result for a task
+    #   result = CMDx::Result.new(my_task)
+    #   result.state   #=> "initialized"
+    #   result.status  #=> "success"
     def initialize(task)
       raise TypeError, "must be a Task or Workflow" unless task.is_a?(Task)
 
@@ -66,27 +58,43 @@ module CMDx
       @metadata = {}
     end
 
-    # Available execution states for task results.
-    #
-    # States represent the execution lifecycle of a task from initialization
-    # through completion or interruption.
-    STATES = [
-      INITIALIZED = "initialized",  # Initial state before execution
-      EXECUTING   = "executing",    # Currently executing task logic
-      COMPLETE    = "complete",     # Successfully completed execution
-      INTERRUPTED = "interrupted"   # Execution was halted due to failure
-    ].freeze
-
-    # Dynamically defines state predicate and callback methods.
-    #
-    # For each state, creates:
-    # - Predicate method (e.g., `executing?`)
-    # - Callback method (e.g., `on_executing`)
     STATES.each do |s|
-      # eg: executing?
+      # Checks if the result is in the specified state.
+      #
+      # @return [Boolean] true if the result matches the state
+      #
+      # @example Check if result is initialized
+      #   result.initialized? #=> true
+      #
+      # @example Check if result is executing
+      #   result.executing? #=> false
+      #
+      # @example Check if result is complete
+      #   result.complete? #=> false
+      #
+      # @example Check if result is interrupted
+      #   result.interrupted? #=> false
       define_method(:"#{s}?") { state == s }
 
-      # eg: on_interrupted { ... }
+      # Executes the provided block if the result is in the specified state.
+      #
+      # @param block [Proc] the block to execute if result matches the state
+      #
+      # @return [Result] returns self for method chaining
+      #
+      # @raise [ArgumentError] if no block is provided
+      #
+      # @example Handle initialized state
+      #   result.on_initialized { |r| puts "Task is ready to start" }
+      #
+      # @example Handle executing state
+      #   result.on_executing { |r| puts "Task is currently running" }
+      #
+      # @example Handle complete state
+      #   result.on_complete { |r| puts "Task finished successfully" }
+      #
+      # @example Handle interrupted state
+      #   result.on_interrupted { |r| puts "Task was interrupted" }
       define_method(:"on_#{s}") do |&block|
         raise ArgumentError, "block required" unless block
 
@@ -95,43 +103,45 @@ module CMDx
       end
     end
 
-    # Marks the result as executed based on current status.
-    #
-    # Transitions to complete state if successful, or interrupted state
-    # if the task has failed or been skipped.
+    # Marks the result as executed by transitioning to complete or interrupted state
+    # based on the current status
     #
     # @return [void]
     #
-    # @example Successful execution
+    # @example Mark successful task as executed
     #   result.executed!
-    #   result.complete?  # => true (if status was success)
+    #   result.complete? #=> true
     #
-    # @example Failed execution
-    #   result.fail!(reason: "Something went wrong")
+    # @example Mark failed task as executed
+    #   result.fail!
     #   result.executed!
-    #   result.interrupted?  # => true
+    #   result.interrupted? #=> true
     def executed!
       success? ? complete! : interrupt!
     end
 
-    # Checks if the result has been executed (completed or interrupted).
+    # Checks if the result has been executed (either complete or interrupted)
     #
-    # @return [Boolean] true if result is complete or interrupted
+    # @return [Boolean] true if the result is complete or interrupted
     #
-    # @example
-    #   result.executed?  # => true if complete? || interrupted?
+    # @example Check if result was executed
+    #   result.executed? #=> false
+    #   result.executed!
+    #   result.executed? #=> true
     def executed?
       complete? || interrupted?
     end
 
-    # Executes a callback if the result has been executed.
+    # Executes the provided block if the result has been executed
     #
-    # @yield [Result] The result instance
-    # @return [Result] Self for method chaining
-    # @raise [ArgumentError] If no block is provided
+    # @param block [Proc] the block to execute if result was executed
     #
-    # @example
-    #   result.on_executed { |r| logger.info "Task finished: #{r.status}" }
+    # @return [Result] returns self for method chaining
+    #
+    # @raise [ArgumentError] if no block is provided
+    #
+    # @example Handle executed results
+    #   result.on_executed { |r| puts "Task execution finished" }
     def on_executed(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -139,14 +149,15 @@ module CMDx
       self
     end
 
-    # Transitions the result to executing state.
+    # Transitions the result to executing state
     #
     # @return [void]
-    # @raise [RuntimeError] If not transitioning from initialized state
     #
-    # @example
+    # @raise [RuntimeError] if not transitioning from initialized state
+    #
+    # @example Start task execution
     #   result.executing!
-    #   result.executing?  # => true
+    #   result.executing? #=> true
     def executing!
       return if executing?
 
@@ -155,14 +166,16 @@ module CMDx
       @state = EXECUTING
     end
 
-    # Transitions the result to complete state.
+    # Transitions the result to complete state
     #
     # @return [void]
-    # @raise [RuntimeError] If not transitioning from executing state
     #
-    # @example
+    # @raise [RuntimeError] if not transitioning from executing state
+    #
+    # @example Complete task execution
+    #   result.executing!
     #   result.complete!
-    #   result.complete?  # => true
+    #   result.complete? #=> true
     def complete!
       return if complete?
 
@@ -171,14 +184,16 @@ module CMDx
       @state = COMPLETE
     end
 
-    # Transitions the result to interrupted state.
+    # Transitions the result to interrupted state
     #
     # @return [void]
-    # @raise [RuntimeError] If trying to interrupt from complete state
     #
-    # @example
+    # @raise [RuntimeError] if transitioning from complete state
+    #
+    # @example Interrupt task execution
+    #   result.executing!
     #   result.interrupt!
-    #   result.interrupted?  # => true
+    #   result.interrupted? #=> true
     def interrupt!
       return if interrupted?
 
@@ -187,25 +202,37 @@ module CMDx
       @state = INTERRUPTED
     end
 
-    # Available execution statuses for task results.
-    #
-    # Statuses represent the outcome of task logic execution.
-    STATUSES = [
-      SUCCESS = "success",  # Task completed successfully
-      SKIPPED = "skipped",  # Task was skipped intentionally
-      FAILED  = "failed"    # Task failed due to error or validation
-    ].freeze
-
-    # Dynamically defines status predicate and callback methods.
-    #
-    # For each status, creates:
-    # - Predicate method (e.g., `success?`)
-    # - Callback method (e.g., `on_success`)
     STATUSES.each do |s|
-      # eg: skipped?
+      # Checks if the result has the specified status.
+      #
+      # @return [Boolean] true if the result matches the status
+      #
+      # @example Check if result is successful
+      #   result.success? #=> true
+      #
+      # @example Check if result is skipped
+      #   result.skipped? #=> false
+      #
+      # @example Check if result is failed
+      #   result.failed? #=> false
       define_method(:"#{s}?") { status == s }
 
-      # eg: on_failed { ... }
+      # Executes the provided block if the result has the specified status.
+      #
+      # @param block [Proc] the block to execute if result matches the status
+      #
+      # @return [Result] returns self for method chaining
+      #
+      # @raise [ArgumentError] if no block is provided
+      #
+      # @example Handle successful status
+      #   result.on_success { |r| puts "Task completed successfully" }
+      #
+      # @example Handle skipped status
+      #   result.on_skipped { |r| puts "Task was skipped: #{r.metadata[:reason]}" }
+      #
+      # @example Handle failed status
+      #   result.on_failed { |r| puts "Task failed: #{r.metadata[:error]}" }
       define_method(:"on_#{s}") do |&block|
         raise ArgumentError, "block required" unless block
 
@@ -214,24 +241,28 @@ module CMDx
       end
     end
 
-    # Checks if the result represents a good outcome (success or skipped).
+    # Checks if the result has a good outcome (not failed)
     #
-    # @return [Boolean] true if not failed
+    # @return [Boolean] true if the result is not failed
     #
-    # @example
-    #   result.good?  # => true if success? || skipped?
+    # @example Check for good outcome
+    #   result.good? #=> true (initially successful)
+    #   result.fail!
+    #   result.good? #=> false
     def good?
       !failed?
     end
 
-    # Executes a callback if the result has a good outcome.
+    # Executes the provided block if the result has a good outcome
     #
-    # @yield [Result] The result instance
-    # @return [Result] Self for method chaining
-    # @raise [ArgumentError] If no block is provided
+    # @param block [Proc] the block to execute if result is good
     #
-    # @example
-    #   result.on_good { |r| logger.info "Task completed successfully" }
+    # @return [Result] returns self for method chaining
+    #
+    # @raise [ArgumentError] if no block is provided
+    #
+    # @example Handle good results
+    #   result.on_good { |r| puts "Task had good outcome" }
     def on_good(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -239,24 +270,28 @@ module CMDx
       self
     end
 
-    # Checks if the result represents a bad outcome (skipped or failed).
+    # Checks if the result has a bad outcome (not successful)
     #
-    # @return [Boolean] true if not successful
+    # @return [Boolean] true if the result is not successful
     #
-    # @example
-    #   result.bad?  # => true if skipped? || failed?
+    # @example Check for bad outcome
+    #   result.bad? #=> false (initially successful)
+    #   result.skip!
+    #   result.bad? #=> true
     def bad?
       !success?
     end
 
-    # Executes a callback if the result has a bad outcome.
+    # Executes the provided block if the result has a bad outcome
+    #
+    # @param block [Proc] the block to execute if result is bad
     #
-    # @yield [Result] The result instance
-    # @return [Result] Self for method chaining
-    # @raise [ArgumentError] If no block is provided
+    # @return [Result] returns self for method chaining
     #
-    # @example
-    #   result.on_bad { |r| logger.error "Task had issues: #{r.status}" }
+    # @raise [ArgumentError] if no block is provided
+    #
+    # @example Handle bad outcome
+    #   result.on_bad { |r| puts "Task had bad outcome: #{r.status}" }
     def on_bad(&)
       raise ArgumentError, "block required" unless block_given?
 
@@ -264,22 +299,21 @@ module CMDx
       self
     end
 
-    # Marks the result as skipped with optional metadata.
+    # Transitions the result to skipped status and sets metadata
     #
-    # Transitions from success to skipped status and halts execution
-    # unless the skip was caused by an original exception.
+    # @param metadata [Hash] additional metadata about why the task was skipped
+    # @option metadata [String] :reason the reason for skipping
+    # @option metadata [Exception] :original_exception the original exception that caused skipping
     #
-    # @param metadata [Hash] Additional metadata about the skip
     # @return [void]
-    # @raise [RuntimeError] If not transitioning from success status
-    # @raise [CMDx::Fault] If halting due to skip (unless original_exception present)
     #
-    # @example Basic skip
-    #   result.skip!(reason: "Order already processed")
-    #   result.skipped?  # => true
+    # @raise [RuntimeError] if not transitioning from success status
+    # @raise [CMDx::Fault] if no original_exception in metadata (via halt!)
     #
-    # @example Skip with exception context
-    #   result.skip!(original_exception: StandardError.new("DB unavailable"))
+    # @example Skip a task with reason
+    #   result.skip!(reason: "Dependencies not met")
+    #   result.skipped? #=> true
+    #   result.metadata[:reason] #=> "Dependencies not met"
     def skip!(**metadata)
       return if skipped?
 
@@ -291,22 +325,21 @@ module CMDx
       halt! unless metadata[:original_exception]
     end
 
-    # Marks the result as failed with optional metadata.
+    # Transitions the result to failed status and sets metadata
     #
-    # Transitions from success to failed status and halts execution
-    # unless the failure was caused by an original exception.
+    # @param metadata [Hash] additional metadata about the failure
+    # @option metadata [String] :error the error message
+    # @option metadata [Exception] :original_exception the original exception that caused failure
     #
-    # @param metadata [Hash] Additional metadata about the failure
     # @return [void]
-    # @raise [RuntimeError] If not transitioning from success status
-    # @raise [CMDx::Fault] If halting due to failure (unless original_exception present)
     #
-    # @example Basic failure
-    #   result.fail!(reason: "Invalid order data", code: 422)
-    #   result.failed?  # => true
+    # @raise [RuntimeError] if not transitioning from success status
+    # @raise [CMDx::Fault] if no original_exception in metadata (via halt!)
     #
-    # @example Failure with exception context
-    #   result.fail!(original_exception: StandardError.new("Validation failed"))
+    # @example Fail a task with error message
+    #   result.fail!(reason: "Database connection failed")
+    #   result.failed? #=> true
+    #   result.metadata[:error] #=> "Database connection failed"
     def fail!(**metadata)
       return if failed?
 
@@ -318,37 +351,35 @@ module CMDx
       halt! unless metadata[:original_exception]
     end
 
-    # Halts execution by raising a fault if the result is not successful.
+    # Halts execution by raising a fault if the result is not successful
     #
     # @return [void]
-    # @raise [CMDx::Fault] If result status is not success
     #
-    # @example
+    # @raise [CMDx::Fault] if the result is not successful
+    #
+    # @example Halt on failed result
     #   result.fail!(reason: "Something went wrong")
-    #   result.halt!  # Raises CMDx::Fault
+    #   result.halt! # raises CMDx::Fault
     def halt!
       return if success?
 
       raise Fault.build(self)
     end
 
-    # Propagates another result's failure status to this result.
+    # Throws the status and metadata from another result to this result
     #
-    # Copies the failure or skip status from another result, merging
-    # metadata and preserving failure chain information.
+    # @param result [CMDx::Result] the result to throw from
+    # @param local_metadata [Hash] additional metadata to merge
     #
-    # @param result [CMDx::Result] The result to propagate from
-    # @param local_metadata [Hash] Additional metadata to merge
     # @return [void]
-    # @raise [TypeError] If result parameter is not a Result instance
     #
-    # @example Propagating failure
-    #   first_result = FirstTask.call
-    #   second_result = SecondTask.call
-    #   second_result.throw!(first_result) if first_result.failed?
+    # @raise [TypeError] if result is not a Result instance
     #
-    # @example Propagating with additional context
-    #   result.throw!(other_result, context: "During order processing")
+    # @example Throw from a failed result
+    #   failed_result = Result.new(task)
+    #   failed_result.fail!(reason: "network timeout")
+    #   current_result.throw!(failed_result)
+    #   current_result.failed? #=> true
     def throw!(result, local_metadata = {})
       raise TypeError, "must be a Result" unless result.is_a?(Result)
 
@@ -358,38 +389,36 @@ module CMDx
       fail!(**md) if result.failed?
     end
 
-    # Finds the result that originally caused a failure in the execution chain.
+    # Finds the result that originally caused a failure in the chain
     #
-    # @return [CMDx::Result, nil] The result that first failed, or nil if not failed
+    # @return [CMDx::Result, nil] the result that caused the failure, or nil if not failed
     #
-    # @example
-    #   failed_result = result.caused_failure
-    #   puts "Original failure: #{failed_result.metadata[:reason]}" if failed_result
+    # @example Find the original failure cause
+    #   result.caused_failure #=> #<Result task=OriginalTask status=failed>
     def caused_failure
       return unless failed?
 
       chain.results.reverse.find(&:failed?)
     end
 
-    # Checks if this result was the original cause of failure.
+    # Checks if this result caused a failure in the chain
     #
-    # @return [Boolean] true if this result caused the failure chain
+    # @return [Boolean] true if this result caused the failure
     #
-    # @example
-    #   result.caused_failure?  # => true if this result started the failure chain
+    # @example Check if result caused failure
+    #   result.caused_failure? #=> true
     def caused_failure?
       return false unless failed?
 
       caused_failure == self
     end
 
-    # Finds the result that threw/propagated the failure to this result.
+    # Finds the result that this failure was thrown to
     #
-    # @return [CMDx::Result, nil] The result that threw the failure, or nil if not failed
+    # @return [CMDx::Result, nil] the result that received the thrown failure, or nil if not failed
     #
-    # @example
-    #   throwing_result = result.threw_failure
-    #   puts "Failure thrown by: #{throwing_result.task.class}" if throwing_result
+    # @example Find where failure was thrown
+    #   result.threw_failure #=> #<Result task=PropagatorTask status=failed>
     def threw_failure
       return unless failed?
 
@@ -397,145 +426,111 @@ module CMDx
       results.find { |r| r.index > index } || results.last
     end
 
-    # Checks if this result threw/propagated a failure.
+    # Checks if this result threw a failure to another result
     #
-    # @return [Boolean] true if this result threw a failure to another result
+    # @return [Boolean] true if this result threw a failure
     #
-    # @example
-    #   result.threw_failure?  # => true if this result propagated failure
+    # @example Check if result threw failure
+    #   result.threw_failure? #=> false
     def threw_failure?
       return false unless failed?
 
       threw_failure == self
     end
 
-    # Checks if this result received a thrown failure (not the original cause).
+    # Checks if this result received a thrown failure from another result
     #
-    # @return [Boolean] true if failed but not the original cause
+    # @return [Boolean] true if this result received a thrown failure
     #
-    # @example
-    #   result.thrown_failure?  # => true if failed due to propagated failure
+    # @example Check if result received thrown failure
+    #   result.thrown_failure? #=> true
     def thrown_failure?
       failed? && !caused_failure?
     end
 
-    # Gets the index of this result within the execution chain.
+    # Returns the index of this result in the chain
     #
-    # @return [Integer] The zero-based index of this result in the chain
+    # @return [Integer] the zero-based index of this result
     #
-    # @example
-    #   result.index  # => 0 for first result, 1 for second, etc.
+    # @example Get result index
+    #   result.index #=> 2
     def index
       chain.index(self)
     end
 
-    # Gets the outcome of the result based on state and status.
+    # Returns the outcome of the result (state for certain cases, status otherwise)
     #
-    # Returns state for initialized results or thrown failures,
-    # otherwise returns the status.
+    # @return [String] the outcome (state or status)
     #
-    # @return [String] The result outcome (state or status)
-    #
-    # @example
-    #   result.outcome  # => "success", "failed", "interrupted", etc.
+    # @example Get result outcome
+    #   result.outcome #=> "success"
+    #   result.fail!
+    #   result.outcome #=> "failed"
     def outcome
       initialized? || thrown_failure? ? state : status
     end
 
-    # Measures and returns the runtime of a block execution.
+    # Gets or measures the runtime of the result
     #
-    # If called without a block, returns the stored runtime value.
-    # If called with a block, executes and measures the execution
-    # time using monotonic clock.
+    # @param block [Proc] optional block to measure runtime for
     #
-    # @yield Block to execute and measure
-    # @return [Float] Runtime in seconds
+    # @return [Float, nil] the runtime in seconds, or nil if not measured
     #
-    # @example Getting stored runtime
-    #   result.runtime  # => 0.5
+    # @example Get existing runtime
+    #   result.runtime #=> 1.234
     #
-    # @example Measuring block execution
-    #   result.runtime do
-    #     # Task execution logic
-    #     perform_work
-    #   end  # => 0.5 (and stores the runtime)
+    # @example Measure runtime with block
+    #   result.runtime { sleep 1 } #=> 1.0
     def runtime(&)
       return @runtime unless block_given?
 
       @runtime = Utils::MonotonicRuntime.call(&)
     end
 
-    # Converts the result to a hash representation.
-    #
-    # @return [Hash] Serialized result data including task info, state, status, and metadata
-    #
-    # @example
-    #   result.to_h
-    #   # => {
-    #   #   class: "ProcessOrderTask",
-    #   #   type: "Task",
-    #   #   index: 0,
-    #   #   id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
-    #   #   state: "complete",
-    #   #   status: "success",
-    #   #   outcome: "success",
-    #   #   metadata: {},
-    #   #   runtime: 0.5
-    #   # }
+    # Converts the result to a hash representation
+    #
+    # @return [Hash] serialized representation of the result
+    #
+    # @example Convert to hash
+    #   result.to_h #=> { state: "complete", status: "success", ... }
     def to_h
       ResultSerializer.call(self)
     end
 
-    # Converts the result to a string representation for inspection.
+    # Returns a string representation of the result
     #
-    # @return [String] Human-readable result description
+    # @return [String] formatted string representation
     #
-    # @example
-    #   result.to_s
-    #   # => "ProcessOrderTask: type=Task index=0 id=018c2b95... state=complete status=success outcome=success runtime=0.5"
+    # @example Convert to string
+    #   result.to_s #=> "Result[complete/success]"
     def to_s
       ResultInspector.call(to_h)
     end
 
-    # Deconstructs the result for array pattern matching.
-    #
-    # Enables pattern matching with array syntax to match against
-    # state and status in order.
+    # Deconstructs the result for pattern matching
     #
-    # @return [Array<String>] Array containing [state, status]
+    # @return [Array<String>] array containing state and status
     #
-    # @example Array pattern matching
-    #   result = ProcessOrderTask.call(order_id: 123)
+    # @example Pattern matching with deconstruct
     #   case result
     #   in ["complete", "success"]
     #     puts "Task completed successfully"
-    #   in ["interrupted", "failed"]
-    #     puts "Task failed"
     #   end
     def deconstruct
       [state, status]
     end
 
-    # Deconstructs the result for hash pattern matching.
+    # Deconstructs the result with keys for pattern matching
     #
-    # Enables pattern matching with hash syntax to match against
-    # specific result attributes.
+    # @param keys [Array<Symbol>, nil] specific keys to include in deconstruction
     #
-    # @param keys [Array<Symbol>] Specific keys to extract (optional)
-    # @return [Hash] Hash containing result attributes
+    # @return [Hash] hash with requested attributes
     #
-    # @example Hash pattern matching
-    #   result = ProcessOrderTask.call(order_id: 123)
+    # @example Pattern matching with specific keys
     #   case result
-    #   in { state: "complete", status: "success" }
-    #     puts "Success!"
-    #   in { state: "interrupted", status: "failed", metadata: { reason: String => reason } }
-    #     puts "Failed: #{reason}"
+    #   in { state: "complete", good: true }
+    #     puts "Task finished well"
     #   end
-    #
-    # @example Specific key extraction
-    #   result.deconstruct_keys([:state, :status])
-    #   # => { state: "complete", status: "success" }
     def deconstruct_keys(keys)
       attributes = {
         state: state,