domainic-type 0.1.0.alpha.2.1.0 → 0.1.0.alpha.3.0.1

data/lib/domainic/type/constraint/resolver.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Domainic
+  module Type
+    module Constraint
+      # @rbs!
+      #  interface _ConstraintClass
+      #    def new: (Type::accessor accessor, ?untyped expectation, **untyped options) -> Behavior
+      #  end
+
+      # A factory class responsible for dynamically loading and resolving constraint types.
+      #
+      # The Resolver handles the dynamic loading and instantiation of constraint classes based on
+      # their type symbols. It manages the conversion of constraint type symbols (like :string or
+      # :numeric) into their corresponding constraint classes (like StringConstraint or
+      # NumericConstraint).
+      #
+      # Key responsibilities:
+      # - Converting constraint type symbols into file paths
+      # - Loading constraint class files dynamically
+      # - Resolving constraint class constants
+      # - Providing clear error messages for unknown constraints
+      #
+      # @example Resolving a string constraint
+      #   resolver = Resolver.new(:string)
+      #   string_constraint_class = resolver.resolve! # => StringConstraint
+      #
+      # @example Resolving an unknown constraint
+      #   resolver = Resolver.new(:unknown)
+      #   resolver.resolve! # raises ArgumentError: Unknown constraint: unknown
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Resolver
+        # @rbs!
+        #  type registry_constraint = { constant: String, require_path: String }
+
+        # @rbs self.@registry: Hash[Symbol, Hash[Symbol, registry_constraint]]
+        # @rbs @constant_name: String
+        # @rbs @constraint_type: Symbol
+        # @rbs @file_name: String
+
+        class << self
+          # Register a new constraint with the resolver.
+          #
+          # @param lookup_key [String, Symbol] The lookup key for the constraint. This is how types should reference
+          #   the constraint when constraining themselves.
+          # @param constant_name [String] The name of the constraint class constant.
+          # @param require_path [String] The path to the constraint class file.
+          #
+          # @raise [ArgumentError] if the constraint is already registered
+          # @return [void]
+          # @rbs (String | Symbol lookup_key, String constant_name, String require_path) -> void
+          def register_constraint(lookup_key, constant_name, require_path)
+            raise ArgumentError, "Constraint already registered: #{lookup_key}" if registry.key?(lookup_key.to_sym)
+
+            registry[lookup_key.to_sym] = { constant: constant_name, require_path: require_path }
+          end
+
+          # Resolve a constraint type to its corresponding class.
+          #
+          # This is a convenience method that creates a new Resolver instance and
+          # immediately resolves the constraint class.
+          #
+          # @param constraint_type [Symbol] The type of constraint to resolve
+          #
+          # @raise [ArgumentError] if the constraint type is unknown
+          # @return [Class] The resolved constraint class
+          # @rbs (Symbol constraint_type) -> _ConstraintClass
+          def resolve!(constraint_type)
+            new(constraint_type).resolve!
+          end
+
+          private
+
+          # The registry of known constraints
+          #
+          # @return [Hash{Symbol => Hash{Symbol => String}}] The constraint registry
+          # @rbs () -> Hash[Symbol, registry_constraint]
+          def registry
+            @registry ||= begin
+              config_file = File.expand_path('../config/registry.yml', File.dirname(__FILE__))
+              raw_config = YAML.load_file(config_file, symbolize_names: true)
+              raw_config[:constraints].transform_values do |value|
+                value.is_a?(Hash) ? value.transform_keys(&:to_sym) : value #: Hash[Symbol, registry_constraint]
+              end
+            end
+          end
+        end
+
+        # Initialize a new Resolver instance.
+        #
+        # @param constraint_type [Symbol] The type of constraint to resolve
+        #
+        # @return [void]
+        # @rbs (String | Symbol constraint_type) -> void
+        def initialize(constraint_type)
+          @constraint_type = constraint_type.to_sym
+        end
+
+        # Resolve the constraint type to its corresponding class.
+        #
+        # This method attempts to load and resolve the constraint class file based on
+        # the constraint type. The constraint class must be defined under the
+        # Domainic::Type::Constraint namespace and follow the naming convention:
+        # "{type}_constraint.rb".
+        #
+        # @example File naming convention
+        #   :string -> string_constraint.rb -> StringConstraint
+        #   :numeric -> numeric_constraint.rb -> NumericConstraint
+        #
+        # @raise [ArgumentError] if the constraint type is unknown
+        # @return [Class] The resolved constraint class
+        # @rbs () -> _ConstraintClass
+        def resolve!
+          load_constraint!
+          constraint_class
+        end
+
+        private
+
+        # Get the constraint class constant.
+        #
+        # Attempts to find the constraint class constant in the Domainic::Type::Constraint
+        # namespace.
+        #
+        # @raise [ArgumentError] if the constant cannot be found
+        # @return [Class] The constraint class constant
+        # @rbs () -> _ConstraintClass
+        def constraint_class
+          registry_constraint = registered
+          raise ArgumentError, "Unknown constraint: #{@constraint_type}" if registry_constraint.nil?
+
+          # @type var registry_constraint: registry_constraint
+          Object.const_get(registry_constraint[:constant])
+        rescue NameError
+          raise ArgumentError, "Unknown constraint: #{@constraint_type}"
+        end
+
+        # Load the constraint class file.
+        #
+        # Attempts to require the constraint class file from the constraints directory.
+        #
+        # @raise [ArgumentError] if the constraint file cannot be loaded
+        # @return [void]
+        # @rbs () -> void
+        def load_constraint!
+          registry_constraint = registered
+          raise ArgumentError, "Unknown constraint: #{@constraint_type}" if registry_constraint.nil?
+
+          # @type var registry_constraint: registry_constraint
+          require registry_constraint[:require_path]
+        rescue LoadError
+          raise ArgumentError, "Constraint require path doesn't exist: #{@constraint_type}"
+        end
+
+        # Fetch the registered constraint from the registry
+        #
+        # @return [Hash{Symbol => String}] The registered constraint
+        # @rbs () -> registry_constraint?
+        def registered
+          registry = self.class.send(:registry)
+          return unless registry.key?(@constraint_type)
+
+          registry[@constraint_type]
+        end
+      end
+    end
+  end
+end

data/lib/domainic/type/constraint/set.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require 'domainic/type/accessors'
+require 'domainic/type/constraint/resolver'
+require 'forwardable'
+
+module Domainic
+  module Type
+    module Constraint
+      # A class managing collections of type constraints.
+      #
+      # The Set class provides a structured way to manage multiple constraints,
+      # organizing them by their accessor method and constraint name. It handles
+      # the creation, storage, and retrieval of constraints while maintaining
+      # their relationships and configuration.
+      #
+      # Key features:
+      # - Organized storage by accessor and constraint name
+      # - Dynamic constraint resolution and creation
+      # - Flexible constraint lookup and enumeration
+      # - Support for both symbol and string identifiers
+      #
+      # @example Creating and managing constraints
+      #   set = Set.new
+      #   set.add(:self, :string, 'being a')
+      #   set.add(:length, :range, 'having length', minimum: 5)
+      #
+      #   set.constraint?(:self, 'being a')  # => true
+      #   set.constraints  # => [StringConstraint, RangeConstraint]
+      #   set.count       # => 2
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class Set
+        extend Forwardable
+
+        # @rbs @lookup: Hash[Type::accessor, Hash[Symbol, Behavior]]
+
+        # Initialize a new empty constraint set.
+        #
+        # @return [void]
+        # @rbs () -> void
+        def initialize
+          @lookup = Type::ACCESSORS.each_with_object({}) do |accessor, lookup|
+            lookup[accessor] = {}
+          end
+        end
+
+        # Add a new constraint to the set.
+        #
+        # Creates and configures a new constraint instance based on the provided type
+        # and configuration. If a constraint with the same accessor and name already
+        # exists, it will be replaced.
+        #
+        # @param accessor [String, Symbol] The accessor method for the constraint
+        # @param constraint_type [String, Symbol] The type of constraint to create
+        # @param expectation [Object, nil] The expected value for the constraint
+        # @param options [Hash{Symbol, String => Object}] Additional options for the constraint
+        #
+        # @option options [String, Symbol] concerning The subject of the constraint.  This is used to namespace
+        #   constraints that may have compatibility issues with other constraints (i,e, min/max size constraints).
+        # @option options [String, Symbol, nil] description The quantifier description of the constraint when given
+        #   a string that ends with "not_described" it will not be included in the constraint set description.
+        # @option options [Boolean] :abort_on_failure Whether to stop on failure
+        # @option options [Array<Proc>, Proc] :coerce_with Coercers to run on the value before validating the
+        #   constraint.
+        #
+        # @return [void]
+        # @rbs (
+        #   Type::accessor accessor,
+        #   String | Symbol constraint_type,
+        #   ?untyped expectation,
+        #   **untyped options
+        #   ) -> void
+        def add(accessor, constraint_type, expectation = nil, **options)
+          accessor, type = [accessor, constraint_type].map(&:to_sym)
+          namespace = options[:concerning]&.to_sym || constraint_type
+
+          # @type var accessor: Type::accessor
+          # @type var type: Symbol
+          # @type var namespace: Symbol
+
+          @lookup[accessor][namespace] ||= build_constraint(type, accessor, options[:description])
+          @lookup[accessor][namespace].expecting(expectation)
+                                      .with_options(options.except(:concerning, :description)) # steep:ignore
+        end
+
+        # Get all constraints in the set.
+        #
+        # @return [Array<Behavior>] Array of all constraints
+        # @rbs () -> Array[Behavior]
+        def all
+          @lookup.values.flat_map(&:values)
+        end
+
+        # @!method all?
+        #   Check if all constraints match the provided block.
+        #
+        #   @yield [Behavior] The constraint to check
+        #   @return [Boolean] true if all constraints match.
+        def_delegators :all, :all?
+
+        # @rbs!
+        #   # Check if all constraints match the provided block.
+        #
+        #   # @yield [Behavior] The constraint to check
+        #   # @return [Boolean] true if all constraints match.
+        #   def all?: () -> bool
+        #           | (Class | Module) -> bool
+        #           | () { (Behavior) -> boolish } -> bool
+
+        # Get the total number of constraints.
+        #
+        # @return [Integer] The number of constraints
+        # @rbs () -> Integer
+        def count
+          @lookup.values.sum(&:count)
+        end
+        alias length count
+        alias size count
+
+        # The aggregate description of all constraints in the set.
+        #
+        # @return [String] The description of all constraints
+        # @rbs () -> String
+        def description
+          Type::ACCESSORS.flat_map do |accessor|
+            @lookup[accessor].values.filter_map(&:full_description)
+          end.join(', ').strip
+        end
+
+        # @!method each
+        #   Iterate over each constraint in the set.
+        #
+        #   @yield [Behavior] The constraint to process
+        #   @return [void]
+        def_delegators :all, :each
+
+        # @rbs!
+        #   # Iterate over each constraint in the set.
+        #
+        #   # @yield [Behavior] The constraint to process
+        #   # @return [void]
+        #   def each: () { (Behavior) -> void } -> void
+
+        # Check if a specific constraint exists.
+        #
+        # @param accessor [Symbol] The accessor method for the constraint
+        # @param concerning [String, Symbol] The subject of the constraint.
+        #
+        # @return [Boolean] true if the constraint exists
+        # @rbs (Type::accessor accessor, Symbol | String concerning) -> bool
+        def exist?(accessor, concerning)
+          accessor = accessor.to_sym
+          # @type var accessor: Type::accessor
+          @lookup.key?(accessor) && @lookup[accessor].key?(concerning.to_sym)
+        end
+        alias has_constraint? exist?
+
+        # Whether any constraints in the set have failed satisfaction.
+        #
+        # @return [Boolean] true if any constraints have failed
+        # @rbs () -> bool
+        def failures?
+          all.any?(&:failure?)
+        end
+
+        # @!method filter_map
+        #   Iterate over each constraint in the set, returning the results of the block excluding nil values.
+        #
+        #   @yield [Behavior] The constraint to process
+        #   @return [Array] The results of the block.
+        def_delegators :all, :filter_map
+
+        # @rbs!
+        #   # Iterate over each constraint in the set, returning the results of the block excluding nil values.
+        #
+        #   # @yield [Behavior] The constraint to process
+        #   # @return [Array] The results of the block.
+        #   def filter_map: () { (Behavior) -> untyped } -> Array[Behavior]
+
+        # Get a specific constraint by its accessor and name.
+        #
+        # @param accessor [Symbol] The accessor method for the constraint
+        # @param concerning [String, Symbol] The subject of the constraint.
+        #
+        # @return [Behavior, nil] The constraint if found, nil otherwise
+        # @rbs (Type::accessor accessor, String | Symbol concerning) -> Behavior?
+        def find(accessor, concerning)
+          # @type var accessor: Type::accessor
+          @lookup.dig(accessor.to_sym, concerning.to_sym)
+        end
+
+        # Prepare a new constraint.
+        #
+        # This is useful for preparing a constraint to use as a sub-constraint for a more complex constraint.
+        #
+        # @param accessor [String, Symbol] The accessor method for the constraint
+        # @param constraint_type [String, Symbol] The type of constraint to create
+        # @param expectation [Object, nil] The expected value for the constraint
+        # @param options [Hash{Symbol, String => Object}] Additional options for the constraint
+        #
+        # @option options [String, Symbol, nil] description The quantifier description of the constraint when given
+        #   a string that ends with "not_described" it will not be included in the constraint set description.
+        # @option options [Boolean] :abort_on_failure Whether to stop on failure
+        # @option options [Array<Proc>, Proc] :coerce_with Coercers to run on the value before validating the
+        #   constraint.
+        #
+        # @return [Behavior] The new constraint instance
+        # @rbs (
+        #   Type::accessor accessor,
+        #   String | Symbol constraint_type,
+        #   ?untyped expectation,
+        #   **untyped options
+        #   ) -> Behavior
+        def prepare(accessor, constraint_type, expectation = nil, **options)
+          build_constraint(constraint_type, accessor, options[:description])
+            .expecting(expectation)
+            .with_options(options.except(:description)) # steep:ignore ArgumentTypeMismatch
+        end
+
+        # The aggregate violation description of all constraints in the set.
+        #
+        # @return [String] The description of all constraints
+        # @rbs () -> String
+        def violation_description
+          Type::ACCESSORS.flat_map do |accessor|
+            @lookup[accessor].values.reject(&:successful?).filter_map(&:full_violation_description)
+          end.join(', ').strip
+        end
+
+        private
+
+        # Build a new constraint instance for the given type.
+        #
+        # @param constraint_type [String, Symbol] The type of constraint to create
+        # @param accessor [String, Symbol] The accessor method for the constraint
+        # @param quantifier_description [String, Symbol] The quantifier description of the constraint
+        #
+        # @return [Behavior] The new constraint instance
+        # @rbs (
+        #   String | Symbol constraint_type,
+        #   Type::accessor accessor,
+        #   (String | Symbol)?,
+        #   ) -> Behavior
+        def build_constraint(constraint_type, accessor, quantifier_description)
+          Resolver.resolve!(constraint_type.to_sym)
+                  .new(accessor.to_sym, quantifier_description)
+        end
+
+        # Ensure that the lookup hash is deep copied when duplicating.
+        #
+        # @param source [Set] The source object to copy
+        #
+        # @return [void]
+        # @rbs override
+        def initialize_copy(source)
+          @lookup = source.instance_variable_get(:@lookup).transform_values do |accessor|
+            accessor.transform_values(&:dup)
+          end
+          super
+        end
+      end
+    end
+  end
+end