domainic-attributer 0.1.0 → 0.2.0

data/lib/domainic/attributer/attribute/callback.rb

@@ -1,16 +1,19 @@
 # frozen_string_literal: true
 
 require 'domainic/attributer/attribute/mixin/belongs_to_attribute'
+require 'domainic/attributer/errors/callback_execution_error'
 
 module Domainic
   module Attributer
     class Attribute
-      # A class responsible for managing change callbacks for an attribute.
+      # A class responsible for managing change callbacks for an attribute
       #
       # This class handles the execution of callbacks that are triggered when an
       # attribute's value changes. Each callback must be a Proc that accepts two
-      # arguments: the old value and the new value.
+      # arguments: the old value, and the new value
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Callback
@@ -21,12 +24,12 @@ module Domainic
 
         include BelongsToAttribute
 
-        # Initialize a new Callback instance.
+        # Initialize a new Callback instance
         #
-        # @param attribute [Attribute] the attribute this Callback belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         # @param handlers [Array<Proc>] the handlers to use for processing
         #
-        # @return [Callback] the new instance of Callback
+        # @return [Callback] the new Callback instance
         # @rbs (Attribute attribute, Array[handler] | handler handlers) -> void
         def initialize(attribute, handlers = [])
           super
@@ -36,21 +39,30 @@ module Domainic
           end.uniq
         end
 
-        # Execute all callbacks for a value change.
+        # Execute all callbacks for a value change
         #
         # @param instance [Object] the instance on which to execute callbacks
         # @param old_value [Object] the previous value
         # @param new_value [Object] the new value
         #
+        # @raise [CallbackExecutionError] if any callback handlers raises an error
         # @return [void]
         # @rbs (untyped instance, untyped old_value, untyped new_value) -> void
         def call(instance, old_value, new_value)
-          @handlers.each { |handler| instance.instance_exec(old_value, new_value, &handler) }
+          errors = []
+
+          @handlers.each do |handler|
+            instance.instance_exec(old_value, new_value, &handler)
+          rescue StandardError => e
+            errors << e
+          end
+
+          raise CallbackExecutionError, errors unless errors.empty?
         end
 
         private
 
-        # Validate that a callback handler is a valid Proc.
+        # Validate that a callback handler is a valid Proc
         #
         # @param handler [Object] the handler to validate
         #
@@ -60,7 +72,7 @@ module Domainic
         def validate_handler!(handler)
           return if handler.is_a?(Proc)
 
-          raise TypeError, "`#{attribute_method_name}`: invalid handler: #{handler.inspect}. Must be a Proc."
+          raise TypeError, "`#{attribute_method_name}`: invalid handler: #{handler.inspect}. Must be a Proc"
         end
       end
     end

data/lib/domainic/attributer/attribute/coercer.rb

@@ -1,16 +1,20 @@
 # frozen_string_literal: true
 
 require 'domainic/attributer/attribute/mixin/belongs_to_attribute'
+require 'domainic/attributer/errors/coercion_execution_error'
+require 'domainic/attributer/undefined'
 
 module Domainic
   module Attributer
     class Attribute
-      # A class responsible for coercing attribute values.
+      # A class responsible for coercing attribute values
       #
       # This class manages the coercion of values assigned to an attribute. Coercion can be
-      # handled by either a Proc that accepts a single value argument, or by referencing an
-      # instance method via Symbol.
+      # handled by either a {Proc} that accepts a single value argument, or by referencing an
+      # instance method via {Symbol}
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Coercer
@@ -23,12 +27,12 @@ module Domainic
 
         # @rbs @handlers: Array[handler]
 
-        # Initialize a new Coercer instance.
+        # Initialize a new {Coercer} instance
         #
-        # @param attribute [Attribute] the attribute this Coercer belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         # @param handlers [Array<Proc, Symbol>] the handlers to use for processing
         #
-        # @return [Coercer] the new instance of Coercer
+        # @return [Coercer] the new Coercer instance
         # @rbs (Attribute attribute, Array[handler] | handler handlers) -> void
         def initialize(attribute, handlers = [])
           super
@@ -38,20 +42,31 @@ module Domainic
           end.uniq
         end
 
-        # Process a value through all coercion handlers.
+        # Process a value through all coercion handlers
         #
         # @param instance [Object] the instance on which to perform coercion
         # @param value [Object] the value to coerce
         #
-        # @return [Object] the coerced value
-        # @rbs (untyped instance, untyped value) -> untyped
+        # @raise [CoercionExecutionError] if a coercion handler raises an error
+        # @return [Object, nil] the coerced value
+        # @rbs (untyped instance, untyped? value) -> untyped?
         def call(instance, value)
-          @handlers.reduce(value) { |accumulator, handler| coerce_value(instance, handler, accumulator) }
+          return value if value == Undefined
+          return value if value.nil? && !@attribute.signature.nilable?
+
+          @handlers.reduce(value) do |accumulator, handler|
+            coerce_value(instance, handler, accumulator)
+          rescue StandardError => e
+            raise CoercionExecutionError.new(
+              "Failed to coerce #{accumulator.inspect} with #{handler.inspect}: #{e.message}",
+              handler
+            )
+          end
         end
 
         private
 
-        # Process a value through a single coercion handler.
+        # Process a value through a single coercion handler
         #
         # @param instance [Object] the instance on which to perform coercion
         # @param handler [Proc, Symbol] the coercion handler
@@ -67,12 +82,12 @@ module Domainic
           when Symbol
             instance.send(handler, value)
           else
-            # We should never get here because we validate the handlers in the initializer.
+            # We should never get here because we validate the handlers in the initializer
             raise TypeError, "`#{attribute_method_name}`: invalid coercer: #{handler}. "
           end
         end
 
-        # Validate that a coercion handler is valid.
+        # Validate that a coercion handler is valid
         #
         # @param handler [Object] the handler to validate
         #

data/lib/domainic/attributer/attribute/mixin/belongs_to_attribute.rb

@@ -1,35 +1,39 @@
 # frozen_string_literal: true
 
+require 'domainic/attributer/attribute'
+
 module Domainic
   module Attributer
     class Attribute
-      # A mixin providing common functionality for classes that belong to an Attribute.
+      # A mixin providing common functionality for classes that belong to an Attribute
       #
       # This module provides initialization and duplication behavior for classes that are owned
       # by and work in conjunction with an Attribute instance. These classes typically handle
-      # specific aspects of attribute processing such as coercion, validation, or callbacks.
+      # specific aspects of attribute processing such as coercion, validation, or callbacks
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       module BelongsToAttribute
         # @rbs @attribute: Attribute
 
-        # Initialize a new instance that belongs to an attribute.
+        # Initialize a new instance that belongs to an {Attribute}
         #
-        # @param attribute [Attribute] the attribute this instance belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         #
-        # @return [void]
+        # @return [BelongsToAttribute] the new BelongsToAttribute instance
         # @rbs (Attribute attribute, *untyped, **untyped) -> void
         def initialize(attribute, ...)
           validate_attribute!(attribute)
           @attribute = attribute
         end
 
-        # Create a duplicate instance associated with a new attribute.
+        # Create a duplicate instance associated with a new {Attribute}
         #
         # @param new_attribute [Attribute] the new attribute to associate with
         #
-        # @return [BelongsToAttribute] a duplicate instance
+        # @return [BelongsToAttribute] duplicate instance with new {Attribute}
         # @rbs (Attribute attribute) -> BelongsToAttribute
         def dup_with_attribute(new_attribute)
           validate_attribute!(new_attribute)
@@ -39,24 +43,23 @@ module Domainic
 
         private
 
-        # Generate a method name for error messages.
+        # Generate a method name for error messages
         #
-        # @return [String] the formatted method name
+        # @return [String] formatted method name
         # @rbs () -> String
         def attribute_method_name
           "#{@attribute.base}##{@attribute.name}"
         end
 
-        # Ensure that an attribute is a valid {Attribute} instance.
+        # Ensure that an {Attribute} is a valid {Attribute} instance
         #
-        # @param attribute [Attribute] the attribute to validate
+        # @param attribute [Attribute] the {Attribute} to validate
         #
-        # @raise [TypeError] if the attribute is not a valid {Attribute} instance
+        # @raise [TypeError] if the attribute is not a valid Attribute instance
         # @return [void]
         # @rbs (Attribute attribute) -> void
         def validate_attribute!(attribute)
           return if attribute.is_a?(Attribute)
-          return if defined?(RSpec::Mocks::TestDouble) && attribute.is_a?(RSpec::Mocks::TestDouble)
 
           raise TypeError,
                 "invalid attribute: #{attribute.inspect}. Must be an Domainic::Attributer::Attribute instance"

data/lib/domainic/attributer/attribute/signature.rb

@@ -5,12 +5,14 @@ require 'domainic/attributer/attribute/mixin/belongs_to_attribute'
 module Domainic
   module Attributer
     class Attribute
-      # A class responsible for managing attribute signature information.
+      # A class responsible for managing attribute signature information
       #
-      # This class encapsulates the type and visibility configuration for an attribute.
+      # This class encapsulates the type and visibility configuration for an {Attribute}
       # It validates and manages whether an attribute is an argument or option, as well
-      # as controlling read and write visibility (public, protected, or private).
+      # as controlling read and write visibility (public, protected, or private)
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Signature
@@ -37,10 +39,10 @@ module Domainic
 
         include BelongsToAttribute
 
-        # @return [Hash{Symbol => Object}] Default options for a new Signature instance.
+        # @return [Hash{Symbol => Object}] Default options for a new Signature instance
         DEFAULT_OPTIONS = { nilable: true, read: :public, required: false, write: :public }.freeze #: default_options
 
-        # Constants defining valid attribute types.
+        # Constants defining valid attribute types
         #
         # @author {https://aaronmallen.me Aaron Allen}
         # @since 0.1.0
@@ -55,7 +57,7 @@ module Domainic
           ALL = [ARGUMENT, OPTION].freeze #: Array[type_symbol]
         end
 
-        # Constants defining valid visibility levels.
+        # Constants defining valid visibility levels
         #
         # @author {https://aaronmallen.me Aaron Allen}
         # @since 0.1.0
@@ -80,30 +82,39 @@ module Domainic
         # @rbs @type: type_symbol
         # @rbs @write_visibility: visibility_symbol
 
+        # Get the position of the attribute
+        #
         # @return [Integer, nil] the position of the attribute
         attr_reader :position #: Integer?
 
+        # Get the visibility level for reading the attribute
+        #
         # @return [Symbol] the visibility level for reading the attribute
         attr_reader :read_visibility #: visibility_symbol
 
+        # Get the attribute type
+        #
         # @return [Symbol] the type of the attribute
         attr_reader :type #: type_symbol
 
+        # Get the visibility level for writing the attribute
+        #
         # @return [Symbol] the visibility level for writing the attribute
         attr_reader :write_visibility #: visibility_symbol
 
-        # Initialize a new Signature instance.
+        # Initialize a new {Signature} instance
         #
-        # @param attribute [Attribute] the attribute this signature belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         # @param options [Hash{Symbol => Object}] the signature options
-        # @option options [Boolean] nilable (true) whether the attribute is allowed to be nil.
+        # @option options [Boolean] nilable (true) whether the attribute is allowed to be nil
         # @option options [Integer, nil] position (nil) optional position for ordered attributes
         # @option options [Symbol] read (:public) the read visibility
         # @option options [Boolean] required (false) whether the attribute is required
         # @option options [Symbol] type the type of attribute
         # @option options [Symbol] write (:public) the write visibility
         #
-        # @return [void]
+        # @raise [ArgumentError] if the configuration is invalid
+        # @return [Signature] the new Signature instance
         # @rbs (
         #   Attribute attribute,
         #   ?nilable: bool,
@@ -127,7 +138,7 @@ module Domainic
           @write_visibility = options.fetch(:write).to_sym
         end
 
-        # Check if this signature is for an argument attribute.
+        # Check if this signature is for an argument attribute
         #
         # @return [Boolean] true if this is an argument attribute
         # @rbs () -> bool
@@ -135,15 +146,15 @@ module Domainic
           @type == TYPE::ARGUMENT
         end
 
-        # Check if the attribute is allowed to be nil.
+        # Check if the attribute allows nil values
         #
-        # @return [Boolean] true if the attribute is allowed to be nil
+        # @return [Boolean] true if the attribute allows nil values
         # @rbs () -> bool
         def nilable?
           @nilable
         end
 
-        # Check if this signature is for an option attribute.
+        # Check if this signature is for an option attribute
         #
         # @return [Boolean] true if this is an option attribute
         # @rbs () -> bool
@@ -151,7 +162,7 @@ module Domainic
           @type == TYPE::OPTION
         end
 
-        # Check if this signature is for an optional attribute.
+        # Check if this signature is for an optional attribute
         #
         # @return [Boolean] true if this is an optional attribute
         # @rbs () -> bool
@@ -159,7 +170,7 @@ module Domainic
           !required?
         end
 
-        # Check if both read and write operations are private.
+        # Check if both read and write operations are private
         #
         # @return [Boolean] true if both read and write are private
         # @rbs () -> bool
@@ -167,7 +178,7 @@ module Domainic
           private_read? && private_write?
         end
 
-        # Check if read operations are private.
+        # Check if read operations are private
         #
         # @return [Boolean] true if read operations are private
         # @rbs () -> bool
@@ -175,7 +186,7 @@ module Domainic
           [VISIBILITY::PRIVATE, VISIBILITY::PROTECTED].include?(@read_visibility)
         end
 
-        # Check if write operations are private.
+        # Check if write operations are private
         #
         # @return [Boolean] true if write operations are private
         # @rbs () -> bool
@@ -183,7 +194,7 @@ module Domainic
           [VISIBILITY::PRIVATE, VISIBILITY::PROTECTED].include?(@write_visibility)
         end
 
-        # Check if both read and write operations are protected.
+        # Check if both read and write operations are protected
         #
         # @return [Boolean] true if both read and write are protected
         # @rbs () -> bool
@@ -191,7 +202,7 @@ module Domainic
           protected_read? && protected_write?
         end
 
-        # Check if read operations are protected.
+        # Check if read operations are protected
         #
         # @return [Boolean] true if read operations are protected
         # @rbs () -> bool
@@ -199,7 +210,7 @@ module Domainic
           @read_visibility == VISIBILITY::PROTECTED
         end
 
-        # Check if write operations are protected.
+        # Check if write operations are protected
         #
         # @return [Boolean] true if write operations are protected
         # @rbs () -> bool
@@ -207,7 +218,7 @@ module Domainic
           @write_visibility == VISIBILITY::PROTECTED
         end
 
-        # Check if both read and write operations are public.
+        # Check if both read and write operations are public
         #
         # @return [Boolean] true if both read and write are public
         # @rbs () -> bool
@@ -215,7 +226,7 @@ module Domainic
           public_read? && public_write?
         end
 
-        # Check if read operations are public.
+        # Check if read operations are public
         #
         # @return [Boolean] true if read operations are public
         # @rbs () -> bool
@@ -223,7 +234,7 @@ module Domainic
           @read_visibility == VISIBILITY::PUBLIC
         end
 
-        # Check if write operations are public.
+        # Check if write operations are public
         #
         # @return [Boolean] true if write operations are public
         # @rbs () -> bool
@@ -231,9 +242,9 @@ module Domainic
           @write_visibility == VISIBILITY::PUBLIC
         end
 
-        # Check if the attribute is required.
+        # Check if this signature requires an attribute value
         #
-        # @return [Boolean] true if the attribute is required
+        # @return [Boolean] true if this signature requires an attribute value
         # @rbs () -> bool
         def required?
           @required
@@ -241,7 +252,7 @@ module Domainic
 
         private
 
-        # Get signature options as a hash.
+        # Get signature options as a hash
         #
         # @return [Hash] the signature options
         # @rbs () -> initialize_options
@@ -256,7 +267,7 @@ module Domainic
           }
         end
 
-        # Validate that a value is a Boolean.
+        # Validate that a value is a boolean
         #
         # @param name [String, Symbol] the name of the attribute being validated
         # @param value [Boolean] the value to validate
@@ -270,7 +281,7 @@ module Domainic
           raise ArgumentError, "`#{attribute_method_name}`: invalid #{name}: #{value}. Must be `true` or `false`."
         end
 
-        # Validate all initialization options.
+        # Validate all initialization options
         #
         # @param options [Hash{Symbol => Object}] the options to validate
         # @option options [Boolean] nilable the nilable flag to validate
@@ -291,7 +302,7 @@ module Domainic
           validate_type!(options[:type])
         end
 
-        # Validate that a position value is valid.
+        # Validate that a position value is valid
         #
         # @param position [Integer, nil] the position to validate
         #
@@ -304,7 +315,7 @@ module Domainic
           raise ArgumentError, "`#{attribute_method_name}`: invalid position: #{position}. Must be Integer or nil."
         end
 
-        # Validate that a type value is valid.
+        # Validate that a type value is valid
         #
         # @param type [Symbol] the type to validate
         #
@@ -318,7 +329,7 @@ module Domainic
                 "`#{attribute_method_name}`: invalid type: #{type}. Must be one of #{TYPE::ALL.join(', ')}"
         end
 
-        # Validate that visibility values are valid.
+        # Validate that visibility values are valid
         #
         # @param type [Symbol] which visibility setting to validate
         # @param value [Symbol] the visibility value to validate

data/lib/domainic/attributer/attribute/validator.rb

@@ -1,16 +1,21 @@
 # frozen_string_literal: true
 
 require 'domainic/attributer/attribute/mixin/belongs_to_attribute'
+require 'domainic/attributer/errors/error'
+require 'domainic/attributer/errors/validation_execution_error'
+require 'domainic/attributer/undefined'
 
 module Domainic
   module Attributer
     class Attribute
-      # A class responsible for validating attribute values.
+      # A class responsible for validating attribute values
       #
       # This class manages the validation of values assigned to an attribute. Validation
-      # can be performed either by a Proc that accepts a single value argument and returns
-      # a boolean, or by any object that responds to the `===` operator.
+      # can be performed either by a {Proc} that accepts a single value argument and returns
+      # a boolean, or by any object that responds to the `===` operator
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Validator
@@ -37,12 +42,12 @@ module Domainic
 
         # @rbs @handlers: Array[handler]
 
-        # Initialize a new Validator instance.
+        # Initialize a new Validator instance
         #
-        # @param attribute [Attribute] the attribute this Validator belongs to
+        # @param attribute [Attribute] the {Attribute} this instance belongs to
         # @param handlers [Array<Class, Module, Object, Proc>] the handlers to use for processing
         #
-        # @return [Validator] the new instance of Validator
+        # @return [Validator] the new Validator instance
         # @rbs (Attribute attribute, Array[handler] | handler handlers) -> void
         def initialize(attribute, handlers = [])
           super
@@ -52,28 +57,28 @@ module Domainic
           end.uniq
         end
 
-        # Validate a value using all configured validators.
+        # Validate a value using all configured validators
         #
         # @param instance [Object] the instance on which to perform validation
         # @param value [Object] the value to validate
         #
         # @raise [ArgumentError] if the value fails validation
+        # @raise [ValidationExecutionError] if errors occur during validation execution
         # @return [void]
         # @rbs (untyped instance, untyped value) -> void
         def call(instance, value)
           return if value == Undefined && handle_undefined!
           return if value.nil? && handle_nil!
-          return if @handlers.all? { |handler| validate_value!(handler, instance, value) }
 
-          raise ArgumentError, "`#{attribute_method_name}`: has invalid value: #{value.inspect}"
+          run_validations!(instance, value)
         end
 
         private
 
-        # Handle a `nil` value.
+        # Handle a nil value
         #
         # @raise [ArgumentError] if the attribute is not nilable
-        # @return [true] if the attribute is nilable
+        # @return [Boolean] true if the attribute is nilable
         # @rbs () -> bool
         def handle_nil!
           return true if @attribute.signature.nilable?
@@ -81,10 +86,10 @@ module Domainic
           raise ArgumentError, "`#{attribute_method_name}`: cannot be nil"
         end
 
-        # Handle an {Undefined} value.
+        # Handle an {Undefined} value
         #
         # @raise [ArgumentError] if the attribute is required
-        # @return [true] if the attribute is optional
+        # @return [Boolean] true if the attribute is optional
         # @rbs () -> bool
         def handle_undefined!
           return true if @attribute.signature.optional?
@@ -92,7 +97,30 @@ module Domainic
           raise ArgumentError, "`#{attribute_method_name}`: is required"
         end
 
-        # Validate that a validation handler is valid.
+        # Run all configured validations
+        #
+        # @param instance [Object] the instance on which to perform validation
+        # @param value [Object] the value to validate
+        #
+        # @raise [ArgumentError] if the value fails validation
+        # @raise [ValidationExecutionError] if errors occur during validation execution
+        # @return [void]
+        # @rbs (untyped instance, untyped value) -> void
+        def run_validations!(instance, value)
+          errors = []
+          is_valid = true
+
+          @handlers.each do |handler|
+            is_valid = validate_value!(handler, instance, value)
+          rescue StandardError => e
+            errors << e
+          end
+
+          raise ValidationExecutionError, errors unless errors.empty?
+          raise ArgumentError, "`#{attribute_method_name}`: has invalid value: #{value.inspect}" unless is_valid
+        end
+
+        # Validate that a validation handler is valid
         #
         # @param handler [Object] the handler to validate
         #
@@ -106,11 +134,13 @@ module Domainic
                            'or an object responding to `#===`.'
         end
 
-        # Validate a value using a single handler.
+        # Validate a value using a single handler
         #
         # @param handler [Object] the handler to use for validation
         # @param instance [Object] the instance on which to perform validation
         # @param value [Object] the value to validate
+        #
+        # @return [Boolean] true if validation succeeds
         # @rbs (handler handler, untyped instance, untyped value) -> bool
         def validate_value!(handler, instance, value)
           if handler.is_a?(Proc)
@@ -118,7 +148,7 @@ module Domainic
           elsif handler.respond_to?(:===)
             handler === value # rubocop:disable Style/CaseEquality
           else
-            # We should never get here because we validate the handlers in the initializer.
+            # We should never get here because we validate the handlers in the initializer
             raise TypeError, "`#{attribute_method_name}`: invalid validator: #{handler.inspect}"
           end
         end