domainic-attributer 0.1.0

data/sig/domainic/attributer/attribute/callback.rbs

@@ -0,0 +1,48 @@
+module Domainic
+  module Attributer
+    class 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.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Callback
+        type handler = ^(untyped old_value, untyped new_value) -> void | Proc
+
+        @handlers: Array[handler]
+
+        include BelongsToAttribute
+
+        # Initialize a new Callback instance.
+        #
+        # @param attribute [Attribute] the attribute this Callback belongs to
+        # @param handlers [Array<Proc>] the handlers to use for processing
+        #
+        # @return [Callback] the new instance of Callback
+        def initialize: (Attribute attribute, Array[handler] | handler handlers) -> void
+
+        # 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
+        #
+        # @return [void]
+        def call: (untyped instance, untyped old_value, untyped new_value) -> void
+
+        private
+
+        # Validate that a callback handler is a valid Proc.
+        #
+        # @param handler [Object] the handler to validate
+        #
+        # @raise [TypeError] if the handler is not a valid Proc
+        # @return [void]
+        def validate_handler!: (handler handler) -> void
+      end
+    end
+  end
+end

data/sig/domainic/attributer/attribute/coercer.rbs

@@ -0,0 +1,59 @@
+module Domainic
+  module Attributer
+    class Attribute
+      # 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.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Coercer
+        type handler = proc | Proc | Symbol
+
+        type proc = ^(untyped value) -> untyped
+
+        include BelongsToAttribute
+
+        @handlers: Array[handler]
+
+        # Initialize a new Coercer instance.
+        #
+        # @param attribute [Attribute] the attribute this Coercer belongs to
+        # @param handlers [Array<Proc, Symbol>] the handlers to use for processing
+        #
+        # @return [Coercer] the new instance of Coercer
+        def initialize: (Attribute attribute, Array[handler] | handler handlers) -> void
+
+        # 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
+        def call: (untyped instance, untyped value) -> untyped
+
+        private
+
+        # 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
+        # @param value [Object] the value to coerce
+        #
+        # @raise [TypeError] if the handler is invalid
+        # @return [Object] the coerced value
+        def coerce_value: (untyped instance, handler, untyped value) -> untyped
+
+        # Validate that a coercion handler is valid.
+        #
+        # @param handler [Object] the handler to validate
+        #
+        # @raise [TypeError] if the handler is not valid
+        # @return [void]
+        def validate_handler!: (handler handler) -> void
+      end
+    end
+  end
+end

data/sig/domainic/attributer/attribute/mixin/belongs_to_attribute.rbs

@@ -0,0 +1,46 @@
+module Domainic
+  module Attributer
+    class 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.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module BelongsToAttribute
+        @attribute: Attribute
+
+        # Initialize a new instance that belongs to an attribute.
+        #
+        # @param attribute [Attribute] the attribute this instance belongs to
+        #
+        # @return [void]
+        def initialize: (Attribute attribute, *untyped, **untyped) -> void
+
+        # Create a duplicate instance associated with a new attribute.
+        #
+        # @param new_attribute [Attribute] the new attribute to associate with
+        #
+        # @return [BelongsToAttribute] a duplicate instance
+        def dup_with_attribute: (Attribute attribute) -> BelongsToAttribute
+
+        private
+
+        # Generate a method name for error messages.
+        #
+        # @return [String] the formatted method name
+        def attribute_method_name: () -> String
+
+        # Ensure that an attribute is a valid {Attribute} instance.
+        #
+        # @param attribute [Attribute] the attribute to validate
+        #
+        # @raise [TypeError] if the attribute is not a valid {Attribute} instance
+        # @return [void]
+        def validate_attribute!: (Attribute attribute) -> void
+      end
+    end
+  end
+end

data/sig/domainic/attributer/attribute/signature.rbs

@@ -0,0 +1,223 @@
+module Domainic
+  module Attributer
+    class Attribute
+      # A class responsible for managing attribute signature information.
+      #
+      # 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).
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Signature
+        type default_options = { nilable: bool, read: visibility_symbol, required: bool, write: visibility_symbol }
+
+        type initialize_options = { ?nilable: bool, ?position: Integer?, ?read: visibility_symbol, ?required: bool, type: type_symbol, ?write: visibility_symbol }
+
+        type type_symbol = :argument | :option
+
+        type visibility_symbol = :private | :protected | :public
+
+        include BelongsToAttribute
+
+        # @return [Hash{Symbol => Object}] Default options for a new Signature instance.
+        DEFAULT_OPTIONS: default_options
+
+        # Constants defining valid attribute types.
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.1.0
+        module TYPE
+          # @return [Symbol] argument type designation
+          ARGUMENT: type_symbol
+
+          # @return [Symbol] option type designation
+          OPTION: type_symbol
+
+          # @return [Array<Symbol>] all valid type values
+          ALL: Array[type_symbol]
+        end
+
+        # Constants defining valid visibility levels.
+        #
+        # @author {https://aaronmallen.me Aaron Allen}
+        # @since 0.1.0
+        module VISIBILITY
+          # @return [Symbol] private visibility level
+          PRIVATE: visibility_symbol
+
+          # @return [Symbol] protected visibility level
+          PROTECTED: visibility_symbol
+
+          # @return [Symbol] public visibility level
+          PUBLIC: visibility_symbol
+
+          # @return [Array<Symbol>] all valid visibility levels
+          ALL: Array[visibility_symbol]
+        end
+
+        @write_visibility: visibility_symbol
+
+        @nilable: bool
+
+        @position: Integer?
+
+        @read_visibility: visibility_symbol
+
+        @required: bool
+
+        @type: type_symbol
+
+        # @return [Integer, nil] the position of the attribute
+        attr_reader position: Integer?
+
+        # @return [Symbol] the visibility level for reading the attribute
+        attr_reader read_visibility: visibility_symbol
+
+        # @return [Symbol] the type of the attribute
+        attr_reader type: type_symbol
+
+        # @return [Symbol] the visibility level for writing the attribute
+        attr_reader write_visibility: visibility_symbol
+
+        # Initialize a new Signature instance.
+        #
+        # @param attribute [Attribute] the attribute this signature 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 [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]
+        def initialize: (Attribute attribute, type: type_symbol, ?nilable: bool, ?position: Integer?, ?read: visibility_symbol, ?required: bool, ?write: visibility_symbol) -> void
+
+        # Check if this signature is for an argument attribute.
+        #
+        # @return [Boolean] true if this is an argument attribute
+        def argument?: () -> bool
+
+        # Check if the attribute is allowed to be nil.
+        #
+        # @return [Boolean] true if the attribute is allowed to be nil
+        def nilable?: () -> bool
+
+        # Check if this signature is for an option attribute.
+        #
+        # @return [Boolean] true if this is an option attribute
+        def option?: () -> bool
+
+        # Check if this signature is for an optional attribute.
+        #
+        # @return [Boolean] true if this is an optional attribute
+        def optional?: () -> bool
+
+        # Check if both read and write operations are private.
+        #
+        # @return [Boolean] true if both read and write are private
+        def private?: () -> bool
+
+        # Check if read operations are private.
+        #
+        # @return [Boolean] true if read operations are private
+        def private_read?: () -> bool
+
+        # Check if write operations are private.
+        #
+        # @return [Boolean] true if write operations are private
+        def private_write?: () -> bool
+
+        # Check if both read and write operations are protected.
+        #
+        # @return [Boolean] true if both read and write are protected
+        def protected?: () -> bool
+
+        # Check if read operations are protected.
+        #
+        # @return [Boolean] true if read operations are protected
+        def protected_read?: () -> bool
+
+        # Check if write operations are protected.
+        #
+        # @return [Boolean] true if write operations are protected
+        def protected_write?: () -> bool
+
+        # Check if both read and write operations are public.
+        #
+        # @return [Boolean] true if both read and write are public
+        def public?: () -> bool
+
+        # Check if read operations are public.
+        #
+        # @return [Boolean] true if read operations are public
+        def public_read?: () -> bool
+
+        # Check if write operations are public.
+        #
+        # @return [Boolean] true if write operations are public
+        def public_write?: () -> bool
+
+        # Check if the attribute is required.
+        #
+        # @return [Boolean] true if the attribute is required
+        def required?: () -> bool
+
+        private
+
+        # Get signature options as a hash.
+        #
+        # @return [Hash] the signature options
+        def to_options: () -> initialize_options
+
+        # 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
+        #
+        # @raise [ArgumentError] if the value is invalid
+        # @return [void]
+        def validate_boolean!: (String | Symbol name, bool value) -> void
+
+        # Validate all initialization options.
+        #
+        # @param options [Hash{Symbol => Object}] the options to validate
+        # @option options [Boolean] nilable the nilable flag to validate
+        # @option options [Integer, nil] position the position value to validate
+        # @option options [Symbol] read the read visibility to validate
+        # @option options [Boolean] required the required flag to validate
+        # @option options [Symbol] type the type to validate
+        # @option options [Symbol] write the write visibility to validate
+        #
+        # @return [void]
+        def validate_initialize_options!: (Hash[Symbol, untyped] options) -> void
+
+        # Validate that a position value is valid.
+        #
+        # @param position [Integer, nil] the position to validate
+        #
+        # @raise [ArgumentError] if the position is invalid
+        # @return [void]
+        def validate_position!: (Integer? position) -> void
+
+        # Validate that a type value is valid.
+        #
+        # @param type [Symbol] the type to validate
+        #
+        # @raise [ArgumentError] if the type is invalid
+        # @return [void]
+        def validate_type!: (type_symbol type) -> void
+
+        # Validate that visibility values are valid.
+        #
+        # @param type [Symbol] which visibility setting to validate
+        # @param value [Symbol] the visibility value to validate
+        #
+        # @raise [ArgumentError] if the visibility is invalid
+        # @return [void]
+        def validate_visibility!: (Symbol type, visibility_symbol value) -> void
+      end
+    end
+  end
+end

data/sig/domainic/attributer/attribute/validator.rbs

@@ -0,0 +1,83 @@
+module Domainic
+  module Attributer
+    class Attribute
+      # 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.
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Validator
+        type handler = proc | Proc | _ValidHandler
+
+        type proc = ^(untyped value) -> bool
+
+        interface _ValidHandler
+          def !=: (untyped value) -> bool
+
+          def ==: (untyped value) -> bool
+
+          def ===: (untyped value) -> bool
+
+          def inspect: () -> untyped
+
+          def is_a?: (Class | Module) -> bool
+
+          def respond_to?: (Symbol) -> bool
+        end
+
+        include BelongsToAttribute
+
+        @handlers: Array[handler]
+
+        # Initialize a new Validator instance.
+        #
+        # @param attribute [Attribute] the attribute this Validator belongs to
+        # @param handlers [Array<Class, Module, Object, Proc>] the handlers to use for processing
+        #
+        # @return [Validator] the new instance of Validator
+        def initialize: (Attribute attribute, Array[handler] | handler handlers) -> void
+
+        # 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
+        # @return [void]
+        def call: (untyped instance, untyped value) -> void
+
+        private
+
+        # Handle a `nil` value.
+        #
+        # @raise [ArgumentError] if the attribute is not nilable
+        # @return [true] if the attribute is nilable
+        def handle_nil!: () -> bool
+
+        # Handle an {Undefined} value.
+        #
+        # @raise [ArgumentError] if the attribute is required
+        # @return [true] if the attribute is optional
+        def handle_undefined!: () -> bool
+
+        # Validate that a validation handler is valid.
+        #
+        # @param handler [Object] the handler to validate
+        #
+        # @raise [TypeError] if the handler is not valid
+        # @return [void]
+        def validate_handler!: (handler handler) -> void
+
+        # 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
+        def validate_value!: (handler handler, untyped instance, untyped value) -> bool
+      end
+    end
+  end
+end

data/sig/domainic/attributer/attribute.rbs

@@ -0,0 +1,150 @@
+module Domainic
+  module Attributer
+    # A class representing a managed attribute in the Domainic::Attributer system.
+    #
+    # This class serves as the core component of the attribute management system.
+    # It coordinates type information, visibility settings, value coercion,
+    # validation, and change notifications for an attribute. Each instance
+    # represents a single attribute definition within a class.
+    #
+    # @author {https://aaronmallen.me Aaron Allen}
+    # @since 0.1.0
+    class Attribute
+      type initialize_options = { ?callbacks: Array[Callback::handler] | Callback::handler, ?coercers: Array[Coercer::handler] | Coercer::handler, ?default: untyped, ?description: String?, name: String | Symbol, ?nilable: bool, ?position: Integer?, ?read: Signature::visibility_symbol, ?required: bool, type: Signature::type_symbol, ?validators: Array[Validator::handler] | Validator::handler, ?write: Signature::visibility_symbol }
+
+      @validator: Validator
+
+      @signature: Signature
+
+      @name: Symbol
+
+      @description: String?
+
+      @default: untyped
+
+      @coercer: Coercer
+
+      @callback: Callback
+
+      @base: __todo__
+
+      # @return [Class, Module] the class or module this attribute belongs to
+      attr_reader base: __todo__
+
+      # @return [String, nil] the description of the attribute
+      attr_reader description: String?
+
+      # @return [Symbol] the name of the attribute
+      attr_reader name: Symbol
+
+      # @return [Signature] the signature configuration for this attribute
+      attr_reader signature: Signature
+
+      # Initialize a new Attribute instance.
+      #
+      # @param base [Class, Module] the class or module this attribute belongs to
+      # @param options [Hash] the options to create the attribute with
+      # @option options [Array<Proc>, Proc] :callbacks callbacks to trigger on value changes
+      # @option options [Array<Proc, Symbol>, Proc, Symbol] :coercers handlers for value coercion
+      # @option options [Object] :default the default value or generator
+      # @option options [String] :description a description of the attribute
+      # @option options [String, Symbol] :name the name of the attribute
+      # @option options [Boolean] :nilable (true) whether the attribute can be nil
+      # @option options [Integer] :position the position for ordered attributes
+      # @option options [Symbol] :read the read visibility
+      # @option options [Boolean] :required (false) whether the attribute is required
+      # @option options [Symbol] :type the type of attribute
+      # @option options [Array<Proc, Object>, Proc, Object] :validators handlers for value validation
+      # @option options [Symbol] :write the write visibility
+      #
+      # @raise [ArgumentError] if the configuration is invalid
+      # @return [void]
+      #
+      def initialize: (__todo__ base, name: String | Symbol, type: Signature::type_symbol, ?callbacks: Array[Callback::handler] | Callback::handler, ?coercers: Array[Coercer::handler] | Coercer::handler, ?default: untyped, ?description: String?, ?nilable: bool, ?position: Integer?, ?read: Signature::visibility_symbol, ?required: bool, ?validators: Array[Validator::handler] | Validator::handler, ?write: Signature::visibility_symbol) -> void
+
+      # Apply a value to the attribute on an instance.
+      #
+      # This method applies all attribute constraints (coercion, validation) to a value
+      # and sets it on the given instance. It manages the complete lifecycle of setting
+      # an attribute value including:
+      # 1. Handling default values
+      # 2. Coercing the value
+      # 3. Validating the result
+      # 4. Setting the value
+      # 5. Triggering callbacks
+      #
+      # @param instance [Object] the instance to set the value on
+      # @param value [Object] the value to set
+      #
+      # @raise [ArgumentError] if the value is invalid
+      # @return [void]
+      def apply!: (untyped instance, untyped value) -> void
+
+      # Check if this attribute has a default value.
+      #
+      # @return [Boolean] true if a default value is set
+      def default?: () -> bool
+
+      # Create a duplicate instance for a new base class.
+      #
+      # @param new_base [Class, Module] the new base class
+      #
+      # @return [Attribute] the duplicated instance
+      def dup_with_base: (__todo__ new_base) -> Attribute
+
+      # Generate the default value for this attribute.
+      #
+      # @param instance [Object] the instance to generate the default for
+      #
+      # @return [Object] the generated default value
+      def generate_default: (untyped instance) -> untyped
+
+      # Merge this attribute's configuration with another.
+      #
+      # @param other [Attribute] the attribute to merge with
+      #
+      # @raise [ArgumentError] if other is not an Attribute
+      # @return [Attribute] a new attribute with merged configuration
+      def merge: (Attribute other) -> Attribute
+
+      private
+
+      # Apply initialization options to create attribute components.
+      #
+      # @param base [Class, Module] the base class
+      # @param options [Hash] the initialization options
+      #
+      # @return [void]
+      def apply_initialize_options!: (__todo__ base, initialize_options options) -> void
+
+      # Initialize a copy of this attribute.
+      #
+      # @param source [Attribute] the source attribute
+      #
+      # @return [Attribute] the initialized copy
+      def initialize_copy: ...
+
+      # Get this attribute's configuration as options.
+      #
+      # @return [Hash] the configuration options
+      def to_options: () -> initialize_options
+
+      # Validate and apply initialization options.
+      #
+      # @param base [Class, Module] the base class
+      # @param options [Hash] the initialization options
+      #
+      # @return [void]
+      def validate_and_apply_initialize_options!: (__todo__ base, initialize_options options) -> void
+
+      # Validate initialization options.
+      #
+      # @param base [Class, Module] the base class
+      # @param options [Hash] the initialization options
+      #
+      # @raise [ArgumentError] if any options are invalid
+      # @return [void]
+      def validate_initialize_options!: (__todo__ base, initialize_options options) -> void
+    end
+  end
+end