cmdx 1.0.0 → 1.1.0

data/lib/cmdx/errors.rb

@@ -1,151 +1,72 @@
 # 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.
+  # Error collection and validation system for CMDx tasks.
   #
-  # 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
+  # This class manages error messages associated with specific attributes,
+  # providing a flexible API for adding, querying, and formatting validation
+  # errors. It supports both individual error messages and collections of
+  # errors per attribute, with various convenience methods for error handling
+  # and display.
   class Errors
 
-    __cmdx_attr_delegator :clear, :delete, :each, :empty?, :key?, :keys, :size, :values,
-                          to: :errors
+    cmdx_attr_delegator :clear, :delete, :empty?, :key?, :keys, :size, :values,
+                        to: :errors
 
-    ##
-    # @!attribute [r] errors
-    #   @return [Hash] internal hash storing error messages by attribute
+    # @return [Hash] internal hash storing error messages by attribute
     attr_reader :errors
 
-    ##
-    # @!method attribute_names
-    #   @return [Array<Symbol>] list of attributes that have errors
+    # @return [Array<Symbol>] list of attributes that have errors
     alias attribute_names keys
 
-    ##
-    # @!method blank?
-    #   @return [Boolean] true if no errors are present
+    # @return [Boolean] true if no errors are present
     alias blank? empty?
 
-    ##
-    # @!method valid?
-    #   @return [Boolean] true if no errors are present
+    # @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.
+    # Creates a new error collection with an empty internal hash.
+    #
+    # @return [Errors] the newly created error collection
     #
-    # @example
-    #   errors = Errors.new
-    #   errors.empty? #=> true
+    # @example Create a new error collection
+    #   errors = CMDx::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
+    # If the attribute already has errors, the new message is appended to the
+    # existing array. Duplicate messages are automatically removed to ensure
+    # each error message appears only once per attribute.
+    #
+    # @param key [Symbol, String] the attribute name to associate the error with
+    # @param value [String] the error message to add
+    #
+    # @return [Array<String>] the array of error messages for the attribute
     #
-    # @example Adding multiple errors
+    # @example Add an error to an attribute
+    #   errors = CMDx::Errors.new
+    #   errors.add(:name, "is required")
+    #   errors[:name] # => ["is required"]
+    #
+    # @example Add multiple errors to the same attribute
     #   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"]
+    #   errors.add(:email, "must be valid")
+    #   errors[:email] # => ["is required", "must be valid"]
+    #
+    # @example Duplicate errors are automatically removed
+    #   errors.add(:age, "must be positive")
+    #   errors.add(:age, "must be positive")
+    #   errors[:age] # => ["must be positive"]
     def add(key, value)
       errors[key] ||= []
       errors[key] << value
@@ -153,18 +74,21 @@ 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
+    # @param key [Symbol, String] the attribute name to check
+    # @param val [String] the error message to look for
     #
-    # @example
+    # @return [Boolean] true if the specific error message exists for the attribute
+    #
+    # @example Check if a specific error exists
+    #   errors = CMDx::Errors.new
     #   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)
+    #   errors.added?(:name, "is required") # => true
+    #   errors.added?(:name, "is invalid") # => false
+    #
+    # @example Check error on attribute without errors
+    #   errors.added?(:missing, "any error") # => false
     def added?(key, val)
       return false unless key?(key)
 
@@ -172,15 +96,14 @@ 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.
+    # Iterates over all error messages, yielding the attribute and message.
     #
-    # @yieldparam key [Symbol] the attribute name
-    # @yieldparam val [String] the error message
-    # @return [Enumerator] if no block given
+    # @yield [Symbol, String] the attribute name and error message
     #
-    # @example
+    # @return [void]
+    #
+    # @example Iterate over all errors
+    #   errors = CMDx::Errors.new
     #   errors.add(:name, "is required")
     #   errors.add(:email, "is invalid")
     #   errors.each { |attr, msg| puts "#{attr}: #{msg}" }
@@ -193,32 +116,36 @@ module CMDx
       end
     end
 
-    ##
-    # Generates a full error message by combining attribute name and message.
+    # Formats an attribute and error message into a full error 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"
+    # @return [String] the formatted full error message
+    #
+    # @example Format a full error message
+    #   errors = CMDx::Errors.new
+    #   errors.full_message(:name, "is required") # => "name is required"
+    #
+    # @example Format with different attribute types
+    #   errors.full_message("email", "must be valid") # => "email must be valid"
     def full_message(key, value)
       "#{key} #{value}"
     end
 
-    ##
-    # Returns an array of all full error messages.
-    # Combines attribute names with their error messages.
+    # Returns an array of all full error messages across all attributes.
     #
     # @return [Array<String>] array of formatted error messages
     #
-    # @example
-    #   errors.add(:email, "is required")
+    # @example Get all full error messages
+    #   errors = CMDx::Errors.new
+    #   errors.add(:name, "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"]
+    #   errors.full_messages # => ["name is required", "email is invalid"]
+    #
+    # @example Empty errors return empty array
+    #   errors = CMDx::Errors.new
+    #   errors.full_messages # => []
     def full_messages
       errors.each_with_object([]) do |(key, arr), memo|
         arr.each { |val| memo << full_message(key, val) }
@@ -226,54 +153,89 @@ 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
+    # @param key [Symbol, String] the attribute name to get messages for
     #
-    # @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)  #=> []
+    # @return [Array<String>] array of formatted error messages for the attribute
+    #
+    # @example Get full messages for a specific attribute
+    #   errors = CMDx::Errors.new
+    #   errors.add(:name, "is required")
+    #   errors.add(:name, "is too short")
+    #   errors.full_messages_for(:name) # => ["name is required", "name is too short"]
+    #
+    # @example Get messages for attribute without errors
+    #   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.
+    # Checks if the error collection contains any errors.
     #
-    # @return [Boolean] true if errors exist
+    # @return [Boolean] true if there are any errors present
     #
-    # @example
-    #   errors = Errors.new
-    #   errors.invalid?  #=> false
+    # @example Check if errors are present
+    #   errors = CMDx::Errors.new
+    #   errors.invalid? # => false
     #   errors.add(:name, "is required")
-    #   errors.invalid?  #=> true
+    #   errors.invalid? # => true
     def invalid?
       !valid?
     end
 
-    ##
+    # Maps over all error messages, yielding the attribute and message to a block.
+    #
+    # Similar to {#each}, but returns an array of the block's return values
+    # instead of iterating without collecting results.
+    #
+    # @yield [Symbol, String] the attribute name and error message
+    # @yieldreturn [Object] the transformed value for each error message
+    #
+    # @return [Array<Object>] array of transformed values from the block
+    #
+    # @example Transform error messages to a custom format
+    #   errors = CMDx::Errors.new
+    #   errors.add(:name, "is required")
+    #   errors.add(:email, "is invalid")
+    #   result = errors.map { |attr, msg| "#{attr.upcase}: #{msg}" }
+    #   result # => ["NAME: is required", "EMAIL: is invalid"]
+    #
+    # @example Extract only attribute names with errors
+    #   errors.map { |attr, _msg| attr } # => [:name, :email]
+    #
+    # @example Return empty array for no errors
+    #   empty_errors = CMDx::Errors.new
+    #   empty_errors.map { |attr, msg| [attr, msg] } # => []
+    def map
+      errors.each_with_object([]) do |(key, _arr), memo|
+        memo.concat(errors[key].map { |val| yield(key, val) })
+      end
+    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
+    # When the same attribute exists in both collections, the error arrays
+    # are combined and duplicates are removed.
     #
-    # @example
-    #   errors1 = Errors.new
-    #   errors1.add(:email, "is required")
+    # @param hash [Hash] hash of errors to merge, with attribute names as keys
     #
-    #   errors2 = { email: ["is invalid"], password: ["is too short"] }
-    #   errors1.merge!(errors2)
+    # @return [Hash] the merged errors hash
     #
-    #   errors1[:email] #=> ["is required", "is invalid"]
-    #   errors1[:password] #=> ["is too short"]
+    # @example Merge errors from another hash
+    #   errors = CMDx::Errors.new
+    #   errors.add(:name, "is required")
+    #   other_errors = { email: ["is invalid"], name: ["is too short"] }
+    #   errors.merge!(other_errors)
+    #   errors[:name] # => ["is required", "is too short"]
+    #   errors[:email] # => ["is invalid"]
+    #
+    # @example Merge with duplicate errors
+    #   errors.add(:age, "must be positive")
+    #   errors.merge!(age: ["must be positive", "must be an integer"])
+    #   errors[:age] # => ["must be positive", "must be an integer"]
     def merge!(hash)
       errors.merge!(hash) do |_, arr1, arr2|
         arr3 = arr1 + arr2
@@ -282,17 +244,20 @@ module CMDx
       end
     end
 
-    ##
-    # Returns error messages for a specific attribute.
+    # Returns the raw error messages for a specific attribute.
     #
-    # @param key [Symbol, String] the attribute name
-    # @return [Array<String>] array of error messages for the attribute
+    # @param key [Symbol, String] the attribute name to get messages for
     #
-    # @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)
+    # @return [Array<String>] array of raw error messages for the attribute
+    #
+    # @example Get raw messages for an attribute
+    #   errors = CMDx::Errors.new
+    #   errors.add(:name, "is required")
+    #   errors.add(:name, "is too short")
+    #   errors.messages_for(:name) # => ["is required", "is too short"]
+    #
+    # @example Get messages for attribute without errors
+    #   errors.messages_for(:missing) # => []
     def messages_for(key)
       return [] unless key?(key)
 
@@ -300,38 +265,36 @@ module CMDx
     end
     alias [] messages_for
 
-    ##
-    # Checks if any errors are present.
+    # Checks if the error collection contains any errors.
     #
-    # @return [Boolean] true if errors exist
+    # @return [Boolean] true if there are any errors present
     #
-    # @example
-    #   errors = Errors.new
-    #   errors.present?  #=> false
+    # @example Check if errors are present
+    #   errors = CMDx::Errors.new
+    #   errors.present? # => false
     #   errors.add(:name, "is required")
-    #   errors.present?  #=> true
+    #   errors.present? # => true
     def present?
       !blank?
     end
 
-    ##
-    # Converts the errors collection to a hash representation.
+    # Converts the error 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 Get raw error messages hash
+    #   errors = CMDx::Errors.new
+    #   errors.add(:name, "is required")
+    #   errors.to_hash # => { name: ["is required"] }
     #
-    # @example Full messages
-    #   errors.add(:email, "is required")
-    #   errors.to_hash(true)  #=> {:email => ["email is required"]}
+    # @example Get full formatted messages hash
+    #   errors.to_hash(true) # => { name: ["name 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
+    # @example Empty errors return empty hash
+    #   errors = CMDx::Errors.new
+    #   errors.to_hash # => {}
     def to_hash(full_messages = false)
       return errors unless full_messages