cmdx 0.5.0 → 1.0.0

data/lib/cmdx/errors.rb

@@ -1,22 +1,151 @@
 # frozen_string_literal: true
 
 module CMDx
+  ##
+  # Errors provides a collection-like interface for managing validation and execution errors
+  # within CMDx tasks. It offers Rails-inspired methods for adding, querying, and formatting
+  # error messages, making it easy to accumulate and present multiple error conditions.
+  #
+  # The Errors class is designed to work seamlessly with CMDx's parameter validation system,
+  # automatically collecting validation failures and providing convenient methods for
+  # error reporting and user feedback.
+  #
+  #
+  # @example Basic error management
+  #   errors = Errors.new
+  #   errors.add(:email, "is required")
+  #   errors.add(:email, "is invalid format")
+  #   errors.add(:password, "is too short")
+  #
+  #   errors.empty?                    #=> false
+  #   errors.size                      #=> 2 (attributes with errors)
+  #   errors[:email]                   #=> ["is required", "is invalid format"]
+  #   errors.full_messages             #=> ["email is required", "email is invalid format", "password is too short"]
+  #
+  # @example Task integration
+  #   class CreateUserTask < CMDx::Task
+  #     required :email, type: :string
+  #     required :password, type: :string
+  #
+  #     def call
+  #       validate_email
+  #       validate_password
+  #
+  #       if errors.present?
+  #         fail!(reason: "Validation failed", validation_errors: errors.full_messages)
+  #       end
+  #
+  #       create_user
+  #     end
+  #
+  #     private
+  #
+  #     def validate_email
+  #       errors.add(:email, "is required") if email.blank?
+  #       errors.add(:email, "is invalid") unless email.include?("@")
+  #     end
+  #
+  #     def validate_password
+  #       errors.add(:password, "is too short") if password.length < 8
+  #     end
+  #   end
+  #
+  # @example Error querying and formatting
+  #   errors = Errors.new
+  #   errors.add(:name, "cannot be blank")
+  #   errors.add(:age, "must be a number")
+  #
+  #   # Checking for specific errors
+  #   errors.key?(:name)                      #=> true
+  #   errors.added?(:name, "cannot be blank") #=> true
+  #   errors.of_kind?(:age, "must be positive") #=> false
+  #
+  #   # Getting messages
+  #   errors.messages_for(:name)              #=> ["cannot be blank"]
+  #   errors.full_messages_for(:name)         #=> ["name cannot be blank"]
+  #
+  #   # Converting to hash
+  #   errors.to_hash                          #=> {:name => ["cannot be blank"], :age => ["must be a number"]}
+  #   errors.to_hash(true)                    #=> {:name => ["name cannot be blank"], :age => ["age must be a number"]}
+  #
+  # @example Rails-style validation
+  #   class ValidateUserTask < CMDx::Task
+  #     required :user_data, type: :hash
+  #
+  #     def call
+  #       user = user_data
+  #
+  #       errors.add(:email, "can't be blank") if user[:email].blank?
+  #       errors.add(:email, "is invalid") unless valid_email?(user[:email])
+  #       errors.add(:age, "must be at least 18") if user[:age] && user[:age] < 18
+  #
+  #       return if errors.invalid?
+  #
+  #       context.validated_user = user
+  #     end
+  #   end
+  #
+  # @see Task Task base class with errors attribute
+  # @see Parameter Parameter validation integration
+  # @see ValidationError Individual validation errors
+  # @since 1.0.0
   class Errors
 
-    __cmdx_attr_delegator :clear, :delete, :each, :empty?, :key?, :keys, :size, :values, to: :errors
+    __cmdx_attr_delegator :clear, :delete, :each, :empty?, :key?, :keys, :size, :values,
+                          to: :errors
 
+    ##
+    # @!attribute [r] errors
+    #   @return [Hash] internal hash storing error messages by attribute
     attr_reader :errors
 
+    ##
+    # @!method attribute_names
+    #   @return [Array<Symbol>] list of attributes that have errors
     alias attribute_names keys
+
+    ##
+    # @!method blank?
+    #   @return [Boolean] true if no errors are present
     alias blank? empty?
+
+    ##
+    # @!method valid?
+    #   @return [Boolean] true if no errors are present
     alias valid? empty?
+
+    ##
+    # Alias for {#key?}. Checks if an attribute has error messages.
     alias has_key? key?
+
+    ##
+    # Alias for {#key?}. Checks if an attribute has error messages.
     alias include? key?
 
+    ##
+    # Initializes a new Errors collection.
+    # Creates an empty hash to store error messages by attribute.
+    #
+    # @example
+    #   errors = Errors.new
+    #   errors.empty? #=> true
     def initialize
       @errors = {}
     end
 
+    ##
+    # Adds an error message to the specified attribute.
+    # Messages are stored in arrays and automatically deduplicated.
+    #
+    # @param key [Symbol, String] the attribute name
+    # @param value [String] the error message
+    # @return [Array<String>] the updated array of messages for the attribute
+    #
+    # @example Adding multiple errors
+    #   errors.add(:email, "is required")
+    #   errors.add(:email, "is invalid format")
+    #   errors.add(:email, "is required")  # Duplicate - ignored
+    #   errors[:email] #=> ["is required", "is invalid format"]
     def add(key, value)
       errors[key] ||= []
       errors[key] << value
@@ -24,6 +153,18 @@ module CMDx
     end
     alias []= add
 
+    ##
+    # Checks if a specific error message has been added to an attribute.
+    #
+    # @param key [Symbol, String] the attribute name
+    # @param val [String] the error message to check for
+    # @return [Boolean] true if the specific error exists
+    #
+    # @example
+    #   errors.add(:name, "is required")
+    #   errors.added?(:name, "is required")     #=> true
+    #   errors.added?(:name, "is too long")     #=> false
+    #   errors.of_kind?(:name, "is required")   #=> true (alias)
     def added?(key, val)
       return false unless key?(key)
 
@@ -31,16 +172,53 @@ module CMDx
     end
     alias of_kind? added?
 
+    ##
+    # Iterates over each error, yielding the attribute and message.
+    # Flattens the error structure so each message is yielded individually.
+    #
+    # @yieldparam key [Symbol] the attribute name
+    # @yieldparam val [String] the error message
+    # @return [Enumerator] if no block given
+    #
+    # @example
+    #   errors.add(:name, "is required")
+    #   errors.add(:email, "is invalid")
+    #   errors.each { |attr, msg| puts "#{attr}: #{msg}" }
+    #   # Output:
+    #   # name: is required
+    #   # email: is invalid
     def each
       errors.each_key do |key|
         errors[key].each { |val| yield(key, val) }
       end
     end
 
+    ##
+    # Generates a full error message by combining attribute name and message.
+    #
+    # @param key [Symbol, String] the attribute name
+    # @param value [String] the error message
+    # @return [String] formatted full message
+    #
+    # @example
+    #   errors.full_message(:email, "is required")  #=> "email is required"
+    #   errors.full_message(:age, "must be positive") #=> "age must be positive"
     def full_message(key, value)
       "#{key} #{value}"
     end
 
+    ##
+    # Returns an array of all full error messages.
+    # Combines attribute names with their error messages.
+    #
+    # @return [Array<String>] array of formatted error messages
+    #
+    # @example
+    #   errors.add(:email, "is required")
+    #   errors.add(:email, "is invalid")
+    #   errors.add(:password, "is too short")
+    #   errors.full_messages
+    #   #=> ["email is required", "email is invalid", "password is too short"]
     def full_messages
       errors.each_with_object([]) do |(key, arr), memo|
         arr.each { |val| memo << full_message(key, val) }
@@ -48,16 +226,54 @@ module CMDx
     end
     alias to_a full_messages
 
+    ##
+    # Returns full error messages for a specific attribute.
+    #
+    # @param key [Symbol, String] the attribute name
+    # @return [Array<String>] array of full messages for the attribute
+    #
+    # @example
+    #   errors.add(:email, "is required")
+    #   errors.add(:email, "is invalid")
+    #   errors.full_messages_for(:email)
+    #   #=> ["email is required", "email is invalid"]
+    #   errors.full_messages_for(:missing)  #=> []
     def full_messages_for(key)
       return [] unless key?(key)
 
       errors[key].map { |val| full_message(key, val) }
     end
 
+    ##
+    # Checks if any errors are present.
+    #
+    # @return [Boolean] true if errors exist
+    #
+    # @example
+    #   errors = Errors.new
+    #   errors.invalid?  #=> false
+    #   errors.add(:name, "is required")
+    #   errors.invalid?  #=> true
     def invalid?
       !valid?
     end
 
+    ##
+    # Merges another hash of errors into this collection.
+    # Combines arrays of messages for attributes that exist in both collections.
+    #
+    # @param hash [Hash] hash of attribute => messages to merge
+    # @return [Hash] the updated errors hash
+    #
+    # @example
+    #   errors1 = Errors.new
+    #   errors1.add(:email, "is required")
+    #
+    #   errors2 = { email: ["is invalid"], password: ["is too short"] }
+    #   errors1.merge!(errors2)
+    #
+    #   errors1[:email] #=> ["is required", "is invalid"]
+    #   errors1[:password] #=> ["is too short"]
     def merge!(hash)
       errors.merge!(hash) do |_, arr1, arr2|
         arr3 = arr1 + arr2
@@ -66,6 +282,17 @@ module CMDx
       end
     end
 
+    ##
+    # Returns error messages for a specific attribute.
+    #
+    # @param key [Symbol, String] the attribute name
+    # @return [Array<String>] array of error messages for the attribute
+    #
+    # @example
+    #   errors.add(:email, "is required")
+    #   errors.add(:email, "is invalid")
+    #   errors.messages_for(:email)  #=> ["is required", "is invalid"]
+    #   errors[:email]               #=> ["is required", "is invalid"] (alias)
     def messages_for(key)
       return [] unless key?(key)
 
@@ -73,10 +300,38 @@ module CMDx
     end
     alias [] messages_for
 
+    ##
+    # Checks if any errors are present.
+    #
+    # @return [Boolean] true if errors exist
+    #
+    # @example
+    #   errors = Errors.new
+    #   errors.present?  #=> false
+    #   errors.add(:name, "is required")
+    #   errors.present?  #=> true
     def present?
       !blank?
     end
 
+    ##
+    # Converts the errors collection to a hash representation.
+    #
+    # @param full_messages [Boolean] whether to include full formatted messages
+    # @return [Hash] hash representation of errors
+    #
+    # @example Raw messages
+    #   errors.add(:email, "is required")
+    #   errors.to_hash  #=> {:email => ["is required"]}
+    #
+    # @example Full messages
+    #   errors.add(:email, "is required")
+    #   errors.to_hash(true)  #=> {:email => ["email is required"]}
+    #
+    # @example Method aliases
+    #   errors.messages              #=> same as to_hash
+    #   errors.group_by_attribute    #=> same as to_hash
+    #   errors.as_json               #=> same as to_hash
     def to_hash(full_messages = false)
       return errors unless full_messages
 

data/lib/cmdx/fault.rb

@@ -1,12 +1,109 @@
 # 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.
+  #
+  # 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
   class Fault < Error
 
-    __cmdx_attr_delegator :task, :run, :context, to: :result
+    __cmdx_attr_delegator :task, :chain, :context,
+                          to: :result
 
+    ##
+    # @!attribute [r] result
+    #   @return [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.
+    #
+    # @param result [Result] the result object containing fault details
+    #
+    # @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">
+    #
+    # @example Fault with I18n message
+    #   # With custom locale configuration
+    #   fault = Fault.new(result)
+    #   fault.message #=> Localized message from I18n
     def initialize(result)
       @result = result
       super(result.metadata[:reason] || I18n.t("cmdx.faults.unspecified", default: "no reason given"))
@@ -14,11 +111,53 @@ 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
+      #
+      # @example Building a skipped fault
+      #   result = MyTask.call(param: "value")
+      #   result.skip!(reason: "Not needed")
+      #   fault = 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)
+      #   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.
+      #
+      # @param tasks [Array<Class>] task classes to match against
+      # @return [Class] a temporary fault class with custom matching logic
+      #
+      # @example Matching 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)
+      #   end
+      #
+      # @example Multiple task matching
+      #   payment_tasks = [ProcessPaymentTask, ValidateCardTask, ChargeCardTask]
+      #   begin
+      #     PaymentWorkflow.call!(payment_data: data)
+      #   rescue CMDx::Failed.for?(*payment_tasks) => e
+      #     # Handle failures from any payment-related task
+      #     process_payment_failure(e)
+      #   end
       def for?(*tasks)
         temp_fault = Class.new(self) do
           def self.===(other)
@@ -29,8 +168,44 @@ 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.
+      #
+      # @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
+      #   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)
+      #   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 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)
+      #   end
       def matches?(&block)
-        raise ArgumentError, "a block is required" unless block_given?
+        raise ArgumentError, "block required" unless block_given?
 
         temp_fault = Class.new(self) do
           def self.===(other)