cmdx 1.0.1 → 1.1.1

data/lib/cmdx/errors.rb

@@ -1,151 +1,60 @@
 # 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
+  # Container for collecting and managing validation and execution errors by attribute.
+  # Provides a comprehensive API for adding, querying, and formatting error messages
+  # with support for multiple errors per attribute and various output formats.
   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 empty errors collection.
     #
-    # @example
-    #   errors = Errors.new
-    #   errors.empty? #=> true
+    # @return [Errors] a new errors instance with empty internal hash
+    #
+    # @example Create new errors 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.
+    # Adds an error message to the specified attribute. Automatically handles
+    # array initialization and prevents duplicate messages for the same attribute.
     #
-    # @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"]
+    # @param key [Symbol, String] the attribute name to associate the error with
+    # @param value [String, Object] the error message or error object to add
+    #
+    # @return [Array] the updated array of error messages for the attribute
+    #
+    # @example Add error to attribute
+    #   errors.add(:name, "can't be blank")
+    #   errors.add(:name, "is too short")
+    #   errors.messages_for(:name) # => ["can't be blank", "is too short"]
+    #
+    # @example Prevent duplicate errors
+    #   errors.add(:email, "is invalid")
+    #   errors.add(:email, "is invalid")
+    #   errors.messages_for(:email) # => ["is invalid"]
     def add(key, value)
       errors[key] ||= []
       errors[key] << value
@@ -153,18 +62,20 @@ 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)
+    # @param key [Symbol, String] the attribute name to check
+    # @param val [String, Object] the error message to look for
+    #
+    # @return [Boolean] true if the error exists for the attribute, false otherwise
+    #
+    # @example Check for specific error
+    #   errors.add(:name, "can't be blank")
+    #   errors.added?(:name, "can't be blank") # => true
+    #   errors.added?(:name, "is invalid") # => false
+    #
+    # @example Check non-existent attribute
+    #   errors.added?(:nonexistent, "error") # => false
     def added?(key, val)
       return false unless key?(key)
 
@@ -172,20 +83,20 @@ 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 each error, yielding the attribute name and error message.
     #
-    # @yieldparam key [Symbol] the attribute name
-    # @yieldparam val [String] the error message
-    # @return [Enumerator] if no block given
+    # @yield [key, value] gives the attribute name and error message for each error
+    # @yieldparam key [Symbol, String] the attribute name
+    # @yieldparam value [String, Object] the error message
     #
-    # @example
-    #   errors.add(:name, "is required")
+    # @return [Hash] the errors hash when no block given
+    #
+    # @example Iterate over all errors
+    #   errors.add(:name, "can't be blank")
     #   errors.add(:email, "is invalid")
     #   errors.each { |attr, msg| puts "#{attr}: #{msg}" }
     #   # Output:
-    #   # name: is required
+    #   # name: can't be blank
     #   # email: is invalid
     def each
       errors.each_key do |key|
@@ -193,32 +104,31 @@ module CMDx
       end
     end
 
-    ##
-    # Generates a full error message by combining attribute name and message.
+    # Formats an error message by combining the attribute name and error value.
     #
     # @param key [Symbol, String] the attribute name
-    # @param value [String] the error message
-    # @return [String] formatted full message
+    # @param value [String, Object] the error message
+    #
+    # @return [String] the formatted full error message
     #
-    # @example
-    #   errors.full_message(:email, "is required")  #=> "email is required"
-    #   errors.full_message(:age, "must be positive") #=> "age must be positive"
+    # @example Format error message
+    #   errors.full_message(:name, "can't be blank") # => "name can't be blank"
+    #   errors.full_message(:email, "is invalid") # => "email is invalid"
     def full_message(key, value)
       "#{key} #{value}"
     end
 
-    ##
-    # Returns an array of all full error messages.
-    # Combines attribute names with their error messages.
+    # Returns all error messages formatted with their attribute names.
     #
     # @return [Array<String>] array of formatted error messages
     #
-    # @example
-    #   errors.add(:email, "is required")
+    # @example Get all formatted messages
+    #   errors.add(:name, "can't be blank")
     #   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 can't be blank", "email is invalid"]
+    #
+    # @example Empty errors collection
+    #   errors.full_messages # => []
     def full_messages
       errors.each_with_object([]) do |(key, arr), memo|
         arr.each { |val| memo << full_message(key, val) }
@@ -226,54 +136,80 @@ module CMDx
     end
     alias to_a full_messages
 
-    ##
-    # Returns full error messages for a specific attribute.
+    # Returns formatted 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 messages for existing attribute
+    #   errors.add(:name, "can't be blank")
+    #   errors.add(:name, "is too short")
+    #   errors.full_messages_for(:name) # => ["name can't be blank", "name is too short"]
+    #
+    # @example Get messages for non-existent attribute
+    #   errors.full_messages_for(:nonexistent) # => []
     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 errors collection contains any validation errors.
+    #
+    # @return [Boolean] true if there are any errors present, false otherwise
     #
-    # @return [Boolean] true if errors exist
+    # @example Check invalid state
+    #   errors.add(:name, "can't be blank")
+    #   errors.invalid? # => true
     #
-    # @example
-    #   errors = Errors.new
-    #   errors.invalid?  #=> false
-    #   errors.add(:name, "is required")
-    #   errors.invalid?  #=> true
+    # @example Check valid state
+    #   errors.invalid? # => false
     def invalid?
       !valid?
     end
 
-    ##
-    # Merges another hash of errors into this collection.
-    # Combines arrays of messages for attributes that exist in both collections.
+    # Transforms each error using the provided block and returns results as an array.
+    #
+    # @yield [key, value] gives the attribute name and error message for transformation
+    # @yieldparam key [Symbol, String] the attribute name
+    # @yieldparam value [String, Object] the error message
+    # @yieldreturn [Object] the transformed value to include in result array
     #
-    # @param hash [Hash] hash of attribute => messages to merge
-    # @return [Hash] the updated errors hash
+    # @return [Array] array of transformed error values
+    #
+    # @example Transform errors to uppercase messages
+    #   errors.add(:name, "can't be blank")
+    #   errors.add(:email, "is invalid")
+    #   errors.map { |attr, msg| msg.upcase } # => ["CAN'T BE BLANK", "IS INVALID"]
+    #
+    # @example Create custom error objects
+    #   errors.map { |attr, msg| { attribute: attr, message: msg } }
+    #   # => [{ attribute: :name, message: "can't be blank" }]
+    def map
+      errors.each_with_object([]) do |(key, _arr), memo|
+        memo.concat(errors[key].map { |val| yield(key, val) })
+      end
+    end
+
+    # Merges another errors hash into this collection, combining arrays for duplicate keys.
     #
-    # @example
-    #   errors1 = Errors.new
-    #   errors1.add(:email, "is required")
+    # @param hash [Hash] hash of errors to merge, with attribute keys and message arrays as values
     #
-    #   errors2 = { email: ["is invalid"], password: ["is too short"] }
-    #   errors1.merge!(errors2)
+    # @return [Hash] the updated internal errors hash
     #
-    #   errors1[:email] #=> ["is required", "is invalid"]
-    #   errors1[:password] #=> ["is too short"]
+    # @example Merge additional errors
+    #   errors.add(:name, "can't be blank")
+    #   other_errors = { email: ["is invalid"], name: ["is too short"] }
+    #   errors.merge!(other_errors)
+    #   errors.messages_for(:name) # => ["can't be blank", "is too short"]
+    #   errors.messages_for(:email) # => ["is invalid"]
+    #
+    # @example Merge with duplicate prevention
+    #   errors.add(:name, "can't be blank")
+    #   duplicate_errors = { name: ["can't be blank", "is required"] }
+    #   errors.merge!(duplicate_errors)
+    #   errors.messages_for(:name) # => ["can't be blank", "is required"]
     def merge!(hash)
       errors.merge!(hash) do |_, arr1, arr2|
         arr3 = arr1 + arr2
@@ -282,17 +218,19 @@ module CMDx
       end
     end
 
-    ##
-    # Returns error messages for a specific attribute.
+    # Returns the raw error messages for a specific attribute without formatting.
     #
-    # @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] array of raw error messages for the attribute
+    #
+    # @example Get raw messages for existing attribute
+    #   errors.add(:name, "can't be blank")
+    #   errors.add(:name, "is too short")
+    #   errors.messages_for(:name) # => ["can't be blank", "is too short"]
+    #
+    # @example Get messages for non-existent attribute
+    #   errors.messages_for(:nonexistent) # => []
     def messages_for(key)
       return [] unless key?(key)
 
@@ -300,38 +238,37 @@ module CMDx
     end
     alias [] messages_for
 
-    ##
-    # Checks if any errors are present.
+    # Checks if the errors collection contains any validation errors.
+    #
+    # @return [Boolean] true if there are any errors present, false otherwise
     #
-    # @return [Boolean] true if errors exist
+    # @example Check for errors presence
+    #   errors.add(:name, "can't be blank")
+    #   errors.present? # => true
     #
-    # @example
-    #   errors = Errors.new
-    #   errors.present?  #=> false
-    #   errors.add(:name, "is required")
-    #   errors.present?  #=> true
+    # @example Check empty collection
+    #   errors.present? # => false
     def present?
       !blank?
     end
 
-    ##
-    # Converts the errors collection to a hash representation.
+    # Converts the errors collection to a hash format, optionally with full formatted messages.
+    #
+    # @param full_messages [Boolean] whether to format messages with attribute names
     #
-    # @param full_messages [Boolean] whether to include full formatted messages
     # @return [Hash] hash representation of errors
+    # @option return [Array<String>] attribute_name array of error messages (raw or formatted)
     #
-    # @example Raw messages
-    #   errors.add(:email, "is required")
-    #   errors.to_hash  #=> {:email => ["is required"]}
+    # @example Get raw errors hash
+    #   errors.add(:name, "can't be blank")
+    #   errors.add(:email, "is invalid")
+    #   errors.to_hash # => { :name => ["can't be blank"], :email => ["is invalid"] }
     #
-    # @example Full messages
-    #   errors.add(:email, "is required")
-    #   errors.to_hash(true)  #=> {:email => ["email is required"]}
+    # @example Get formatted errors hash
+    #   errors.to_hash(true) # => { :name => ["name can't be blank"], :email => ["email is invalid"] }
     #
-    # @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 collection
+    #   errors.to_hash # => {}
     def to_hash(full_messages = false)
       return errors unless full_messages