domainic-attributer 0.1.0 → 0.2.0

data/sig/domainic/attributer/dsl/initializer.rbs

@@ -1,13 +1,15 @@
 module Domainic
   module Attributer
     module DSL
-      # A class responsible for handling object initialization with attributes.
+      # A class responsible for handling object initialization with attributes
       #
       # This class manages the process of setting attribute values during object
       # initialization. It handles both positional arguments and keyword options,
       # applying them to their corresponding attributes while respecting default
-      # values and required attributes.
+      # values and required attributes
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class Initializer
@@ -19,21 +21,21 @@ module Domainic
 
         @attributes: AttributeSet
 
-        # Initialize a new Initializer.
+        # Initialize a new Initializer
         #
         # @param base [Object] the instance being initialized
         #
-        # @return [void]
+        # @return [Initializer] the new Initializer instance
         def initialize: (Object base) -> void
 
-        # Assign values to attributes.
+        # Assign values to attributes
         #
         # Validates and applies both positional arguments and keyword options to
         # their corresponding attributes. Raises an error if required arguments
-        # are missing.
+        # are missing
         #
-        # @param arguments [Array] positional arguments to assign
-        # @param keyword_arguments [Hash] keyword arguments to assign
+        # @param arguments [Array<Object>] positional arguments to assign
+        # @param keyword_arguments [Hash{Symbol => Object}] keyword arguments to assign
         #
         # @raise [ArgumentError] if required arguments are missing
         # @return [void]
@@ -41,46 +43,46 @@ module Domainic
 
         private
 
-        # Access to the current attribute set.
+        # Access to the current attribute set
         #
         # @return [AttributeSet] the attribute set for this instance
         attr_reader attributes: AttributeSet
 
-        # Apply positional arguments to their attributes.
+        # Apply positional arguments to their attributes
         #
-        # @param arguments [Array] the positional arguments to apply
+        # @param arguments [Array<Object>] the positional arguments to apply
         #
         # @return [void]
         def apply_arguments: (Array[untyped]) -> void
 
-        # Apply keyword arguments to their attributes.
+        # Apply keyword arguments to their attributes
         #
-        # @param options [Hash] the keyword options to apply
+        # @param options [Hash{Symbol => Object}] the keyword options to apply
         #
         # @return [void]
         def apply_options!: (Hash[String | Symbol, untyped]) -> void
 
-        # Get all argument attributes.
+        # Get all argument attributes
         #
         # @return [Array<Attribute>] the argument attributes
         def argument_attributes: () -> Array[Attribute]
 
-        # Assign a value to an attribute.
+        # Assign a value to an attribute
         #
         # @param attribute_name [Symbol] the name of the attribute
         # @param value [Object] the value to assign
         #
         # @return [void]
-        def assign_value: (untyped attribute_name, untyped value) -> untyped
+        def assign_value: (String | Symbol attribute_name, untyped value) -> void
 
-        # Get all option attributes.
+        # Get all option attributes
         #
         # @return [Array<Attribute>] the option attributes
         def option_attributes: () -> Array[Attribute]
 
-        # Validate that all required positional arguments are provided.
+        # Validate that all required positional arguments are provided
         #
-        # @param arguments [Array] the arguments to validate
+        # @param arguments [Array<Object>] the arguments to validate
         #
         # @raise [ArgumentError] if required arguments are missing
         # @return [void]

data/sig/domainic/attributer/dsl/method_injector.rbs

@@ -1,13 +1,15 @@
 module Domainic
   module Attributer
     module DSL
-      # A class responsible for injecting attribute methods into classes.
+      # A class responsible for injecting attribute methods into classes
       #
       # This class handles the creation of reader and writer methods for attributes,
       # ensuring they are injected safely without overwriting existing methods. It
       # respects visibility settings and properly handles value assignment through
-      # the attribute system.
+      # the attribute system
       #
+      # @api private
+      # @!visibility private
       # @author {https://aaronmallen.me Aaron Allen}
       # @since 0.1.0
       class MethodInjector
@@ -15,48 +17,48 @@ module Domainic
 
         @base: __todo__
 
-        # Inject methods for an attribute into a class.
+        # Inject methods for an attribute into a class
         #
         # @param base [Class, Module] the class to inject methods into
-        # @param attribute [Attribute] the attribute to create methods for
+        # @param attribute [Attribute] the {Attribute} to create methods for
         #
         # @return [void]
         def self.inject!: (__todo__ base, Attribute attribute) -> void
 
-        # Initialize a new MethodInjector.
+        # Initialize a new MethodInjector
         #
         # @param base [Class, Module] the class to inject methods into
-        # @param attribute [Attribute] the attribute to create methods for
+        # @param attribute [Attribute] the {Attribute} to create methods for
         #
-        # @return [void]
+        # @return [MethodInjector] the new MethodInjector instance
         def initialize: (__todo__ base, Attribute attribute) -> void
 
-        # Inject reader and writer methods.
+        # Inject reader and writer methods
         #
         # @return [void]
         def inject!: () -> void
 
         private
 
-        # Define a method if it doesn't already exist.
+        # Define a method if it doesn't already exist
         #
         # @param method_name [Symbol] the name of the method to define
-        # @yield the method body to define
         #
+        # @yield the method body to define
         # @return [void]
         def define_safe_method: (Symbol method_name) { (?) [self: untyped] -> void } -> void
 
-        # Inject the attribute reader method.
+        # Inject the attribute reader method
         #
-        # Creates a reader method with the configured visibility.
+        # Creates a reader method with the configured visibility
         #
         # @return [void]
         def inject_reader!: () -> void
 
-        # Inject the attribute writer method.
+        # Inject the attribute writer method
         #
         # Creates a writer method that processes values through the attribute
-        # system before assignment. Sets the configured visibility.
+        # system before assignment. Sets the configured visibility
         #
         # @return [void]
         def inject_writer!: () -> void

data/sig/domainic/attributer/errors/aggregate_error.rbs

@@ -0,0 +1,28 @@
+module Domainic
+  module Attributer
+    # A specialized error class that combines multiple errors into a single error
+    #
+    # This class encapsulates multiple errors that occur during a single operation and
+    # need to be reported together. It maintains a list of individual errors while providing
+    # a formatted message that includes details from all errors
+    #
+    # @api private
+    # @!visibility private
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class AggregateError < Error
+      # Get the collection of errors that were aggregated
+      #
+      # @return [Array<StandardError>] the collection of errors
+      attr_reader errors: Array[StandardError]
+
+      # Initialize a new AggregateError instance
+      #
+      # @param message [String] the main error message
+      # @param errors [Array<StandardError>] the collection of errors to aggregate
+      #
+      # @return [AggregateError] the new AggregateError instance
+      def initialize: (String message, Array[StandardError] errors) -> void
+    end
+  end
+end

data/sig/domainic/attributer/errors/callback_execution_error.rbs

@@ -0,0 +1,23 @@
+module Domainic
+  module Attributer
+    # A specialized error class for callback execution failures
+    #
+    # This error class is used when one or more callbacks fail during attribute value
+    # changes. It aggregates all callback-related errors into a single error with a
+    # descriptive message listing each individual failure
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class CallbackExecutionError < AggregateError
+      # Initialize a new CallbackExecutionError instance
+      #
+      # @api private
+      # @!visibility private
+      #
+      # @param errors [Array<StandardError>] the collection of callback errors to aggregate
+      #
+      # @return [CallbackExecutionError] the new CallbackExecutionError instance
+      def initialize: (Array[StandardError] errors) -> void
+    end
+  end
+end

data/sig/domainic/attributer/errors/coercion_execution_error.rbs

@@ -0,0 +1,29 @@
+module Domainic
+  module Attributer
+    # A specialized error class for coercion execution failures
+    #
+    # This error class is used when a coercion fails during attribute value
+    # processing. It captures the failing coercer to provide context about which
+    # step in the coercion chain caused the failure
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class CoercionExecutionError < Error
+      # Get the coercer that failed
+      #
+      # @return [Proc, Symbol] the coercer that failed
+      attr_reader coercer: Attribute::Coercer::handler
+
+      # Initialize a new CoercionExecutionError instance
+      #
+      # @api private
+      # @!visibility private
+      #
+      # @param message [String] the error message
+      # @param coercer [Proc, Symbol] the coercer that failed
+      #
+      # @return [CoercionExecutionError] the new CoercionExecutionError instance
+      def initialize: (String message, Attribute::Coercer::handler coercer) -> void
+    end
+  end
+end

data/sig/domainic/attributer/errors/error.rbs

@@ -0,0 +1,17 @@
+module Domainic
+  module Attributer
+    # Base error class for all Attributer-related errors
+    #
+    # This class serves as the foundation for Attributer's error hierarchy, allowing
+    # for specific error types to be caught and handled appropriately. All custom
+    # errors within the Attributer system should inherit from this class to maintain
+    # a consistent error handling pattern
+    #
+    # @api private
+    # @!visibility private
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class Error < StandardError
+    end
+  end
+end

data/sig/domainic/attributer/errors/validation_execution_error.rbs

@@ -0,0 +1,23 @@
+module Domainic
+  module Attributer
+    # A specialized error class for validation execution failures
+    #
+    # This error class is used when one or more validations encounter errors during
+    # their execution. It aggregates all validation-related errors into a single
+    # error with a descriptive message listing each individual failure
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.2.0
+    class ValidationExecutionError < AggregateError
+      # Initialize a new ValidationExecutionError instance
+      #
+      # @api private
+      # @!visibility private
+      #
+      # @param errors [Array<StandardError>] the collection of validation errors to aggregate
+      #
+      # @return [ValidationExecutionError] the new ValidationExecutionError instance
+      def initialize: (Array[StandardError] errors) -> void
+    end
+  end
+end

data/sig/domainic/attributer/instance_methods.rbs

@@ -1,10 +1,10 @@
 module Domainic
   module Attributer
-    # A module providing instance-level attribute functionality.
+    # A module providing instance-level attribute functionality
     #
-    # This module defines instance methods for objects that include Domainic::Attributer.
+    # This module defines instance methods for objects that include {Domainic::Attributer}.
     # It provides initialization handling and attribute serialization capabilities, making
-    # it easy to work with attribute values in a consistent way.
+    # it easy to work with attribute values in a consistent way
     #
     # @example Basic usage
     #   class Person
@@ -21,7 +21,7 @@ module Domainic
     # @author {https://aaronmallen.me Aaron Allen}
     # @since 0.1.0
     module InstanceMethods
-      # Initialize a new instance with attribute values.
+      # Initialize a new instance with attribute values
       #
       # Handles both positional arguments and keyword options, applying them to their
       # corresponding attributes. This process includes:
@@ -30,17 +30,20 @@ module Domainic
       # 3. Type validation and coercion
       # 4. Change notifications
       #
+      # @example
+      #   person = Person.new('Alice', age: 30)
+      #
       # @raise [ArgumentError] if required arguments are missing
-      # @return [void]
+      # @return [InstanceMethods] the new InstanceMethods instance
       def initialize: (*untyped arguments, **untyped keyword_arguments) -> void
 
-      # Convert public attribute values to a hash.
+      # Convert public attribute values to a hash
       #
       # Creates a hash containing all public readable attributes and their current values.
       # Any attributes marked as private or protected for reading are excluded from
-      # the result.
+      # the result
       #
-      # @example Basic conversion
+      # @example
       #   person = Person.new('Alice', age: 30)
       #   person.to_h  # => { name: 'Alice', age: 30 }
       #

data/sig/domainic/attributer/undefined.rbs

@@ -1,12 +1,14 @@
 module Domainic
   module Attributer
-    # A singleton object representing an undefined value.
+    # A singleton object representing an undefined value
     #
-    # This object is used throughout Domainic::Attributer to represent values that
+    # This object is used throughout {Domainic::Attributer} to represent values that
     # are explicitly undefined, as opposed to nil which represents the absence of
     # a value. It is immutable and implements custom string representations for
-    # debugging purposes.
+    # debugging purposes
     #
+    # @api private
+    # @!visibility private
     # @author {https://aaronmallen.me Aaron Allen}
     # @since 0.1.0
     Undefined: Object

data/sig/domainic/attributer.rbs

@@ -1,69 +1,130 @@
 module Domainic
-  # Core functionality for defining and managing Ruby class attributes.
+  # `Domainic::Attributer` is a powerful toolkit that brings clarity and safety to your Ruby class attributes.
+  # Ever wished your class attributes could:
   #
-  # This module provides a flexible attribute system for Ruby classes that supports
-  # positional arguments and keyword options with features like type validation,
-  # coercion, and visibility control.
+  # * Validate themselves to ensure they only accept correct values?
+  # * Transform input data automatically into the right format?
+  # * Have clear, enforced visibility rules?
+  # * Handle their own default values intelligently?
+  # * Tell you when they change?
+  # * Distinguish between required arguments and optional settings?
   #
-  # Can be included directly with default method names or customized via {Domainic.Attributer}.
+  # That's exactly what `Domainic::Attributer` does! It provides a declarative way to define and manage attributes
+  # in your Ruby classes, ensuring data integrity and clear interfaces. It's particularly valuable for:
   #
-  # @example Basic usage with default method names
-  #   class Person
+  # * Domain models and value objects
+  # * Service objects and command patterns
+  # * Configuration objects
+  # * Any class where attribute behavior matters
+  #
+  # Think of it as giving your attributes a brain - they know what they want, how they should behave, and
+  # they're not afraid to speak up when something's not right!
+  #
+  # @see file:docs/USAGE.md Usage Guide
+  # @abstract Can be included directly with default method names or customized via {.Attributer}
+  #
+  # @example Basic usage
+  #   class SuperDev
   #     include Domainic::Attributer
   #
-  #     argument :name
-  #     option :age
+  #     argument :code_name, String
+  #
+  #     option :power_level, Integer, default: 9000
+  #     option :favorite_gem do
+  #       validate_with ->(val) { val.to_s.end_with?('ruby') }
+  #       coerce_with ->(val) { val.to_s.downcase }
+  #       non_nilable
+  #     end
   #   end
   #
-  # @example Custom method names
-  #   class Person
-  #     include Domainic.Attributer(argument: :param, option: :opt)
+  #   dev = SuperDev.new('RubyNinja', favorite_gem: 'RAILS_RUBY')
+  #   # => #<SuperDev:0x00000001083aeb58 @code_name="RubyNinja", @favorite_gem="rails_ruby", @power_level=9000>
   #
-  #     param :name
-  #     opt :age
-  #   end
+  #   dev.favorite_gem # => "rails_ruby"
+  #   dev.power_level = 9001 # => 9001
+  #   dev.power_level = 'over 9000'
+  #   # `SuperDev#power_level`: has invalid value: "over 9000" (ArgumentError)
   #
   # @author {https://aaronmallen.me Aaron Allen}
   # @since 0.1.0
   module Attributer
-    # Create a customized Attributer module.
+    # Create a customized Attributer module
+    #
+    # @!visibility private
+    # @api private
     #
     # @param argument [Symbol, String] custom name for the argument method
     # @param option [Symbol, String] custom name for the option method
+    #
     # @return [Module] configured Attributer module
     def self.call: (?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> Module
 
-    # Handle direct module inclusion.
+    # Handle direct module inclusion
+    #
+    # @!visibility private
+    # @api private
     #
     # @param base [Class, Module] the including class/module
+    #
     # @return [void]
     def self.included: (untyped base) -> void
 
-    # Configure base class with Attributer functionality.
+    # Configure base class with Attributer functionality
     #
     # @param base [Class, Module] the target class/module
-    # @param options [Hash] method name customization options
+    # @param options [Hash{Symbol => String, Symbol}] method name customization options
+    #
     # @return [void]
     private def self.include_attributer: (untyped base, ?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> void
 
-    # Set up custom method names.
+    # Set up custom method names
     #
     # @param base [Class, Module] the target class/module
-    # @param options [Hash] method name customization options
+    # @param options [Hash{Symbol => String, Symbol}] method name customization options
+    #
     # @return [void]
     private def self.inject_custom_methods!: (untyped base, ?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> void
   end
 
-  # Create a customized Attributer module.
-  #
-  # Provides a convenient way to include Attributer with customized method names.
+  # Provides a convenient way to include {Attributer} with customized method names
   #
-  # @example
+  # @example Customizing method names
   #   class Person
   #     include Domainic.Attributer(argument: :param, option: :opt)
+  #
+  #     param :name, String
+  #     opt :age, Integer
   #   end
   #
-  # @param options [Hash] method name customization options
-  # @return [Module] configured Attributer module
+  #   Person.respond_to?(:argument) # => false
+  #   Person.respond_to?(:param)  # => true
+  #   Person.respond_to?(:option) # => false
+  #   Person.respond_to?(:opt)  # => true
+  #
+  #   person = Person.new('Alice', age: 30)
+  #   # => #<Person:0x000000010865d188 @age=30, @name="Alice">
+  #
+  # @example Turning off a method
+  #
+  #   class Person
+  #     include Domainic.Attributer(argument: nil)
+  #
+  #     option :name, String
+  #     option :age, Integer
+  #   end
+  #
+  #   Person.respond_to?(:argument)  # => false
+  #   Person.respond_to?(:option) # => true
+  #
+  #   person = Person.new(name: 'Alice', age: 30)
+  #   # => #<Person:0x000000010865d188 @age=30, @name="Alice">
+  #
+  # @param options [Hash{Symbol => String, Symbol, nil}] method name customization options
+  # @option options [String, Symbol, nil] :argument custom name for the {Attributer::ClassMethods#argument argument}
+  #   method. Set to `nil` to disable the method entirely
+  # @option options [String, Symbol, nil] :option custom name for the {Attributer::ClassMethods#option option}
+  #   method. Set to `nil` to disable the method entirely
+  #
+  # @return [Module] the configured {Attributer} module
   def self.Attributer: (?argument: (String | Symbol)?, ?option: (String | Symbol)?) -> Module
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: domainic-attributer
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Aaron Allen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-12-12 00:00:00.000000000 Z
+date: 2025-01-01 00:00:00.000000000 Z
 dependencies: []
 description: Your domain objects deserve better than plain old attributes. Level up
   your DDD game with powerful, configurable, and well-documented class attributes
@@ -19,9 +19,11 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - CHANGELOG.md
 - LICENSE
 - README.md
+- docs/USAGE.md
 - lib/domainic-attributer.rb
 - lib/domainic/attributer.rb
 - lib/domainic/attributer/attribute.rb
@@ -37,6 +39,11 @@ files:
 - lib/domainic/attributer/dsl/attribute_builder/option_parser.rb
 - lib/domainic/attributer/dsl/initializer.rb
 - lib/domainic/attributer/dsl/method_injector.rb
+- lib/domainic/attributer/errors/aggregate_error.rb
+- lib/domainic/attributer/errors/callback_execution_error.rb
+- lib/domainic/attributer/errors/coercion_execution_error.rb
+- lib/domainic/attributer/errors/error.rb
+- lib/domainic/attributer/errors/validation_execution_error.rb
 - lib/domainic/attributer/instance_methods.rb
 - lib/domainic/attributer/undefined.rb
 - sig/domainic-attributer.rbs
@@ -54,18 +61,24 @@ files:
 - sig/domainic/attributer/dsl/attribute_builder/option_parser.rbs
 - sig/domainic/attributer/dsl/initializer.rbs
 - sig/domainic/attributer/dsl/method_injector.rbs
+- sig/domainic/attributer/errors/aggregate_error.rbs
+- sig/domainic/attributer/errors/callback_execution_error.rbs
+- sig/domainic/attributer/errors/coercion_execution_error.rbs
+- sig/domainic/attributer/errors/error.rbs
+- sig/domainic/attributer/errors/validation_execution_error.rbs
 - sig/domainic/attributer/instance_methods.rbs
 - sig/domainic/attributer/undefined.rbs
 - sig/manifest.yaml
-homepage: https://github.com/domainic/domainic/tree/domainic-attributer-v0.1.0/domainic-attributer
+homepage: https://github.com/domainic/domainic/tree/domainic-attributer-v0.2.0/domainic-attributer
 licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/domainic/domainic/issues
-  changelog_uri: https://github.com/domainic/domainic/releases/tag/domainic-attributer-v0.1.0
-  homepage_uri: https://github.com/domainic/domainic/tree/domainic-attributer-v0.1.0/domainic-attributer
+  changelog_uri: https://github.com/domainic/domainic/releases/tag/domainic-attributer-v0.2.0
+  documentation_uri: https://rubydoc.info/gems/domainic-attributer/0.2.0
+  homepage_uri: https://github.com/domainic/domainic/tree/domainic-attributer-v0.2.0/domainic-attributer
   rubygems_mfa_required: 'true'
-  source_code_uri: https://github.com/domainic/domainic/tree/domainic-attributer-v0.1.0/domainic-attributer
+  source_code_uri: https://github.com/domainic/domainic/tree/domainic-attributer-v0.2.0/domainic-attributer
 post_install_message:
 rdoc_options: []
 require_paths: