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

data/sig/domainic/type/constraint/constraints/ordering_constraint.rbs

@@ -0,0 +1,60 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating that collection elements are in sorted order.
+      #
+      # This constraint ensures that elements in a collection are in ascending order
+      # by comparing the collection to its sorted version. The constraint works with
+      # any collection whose elements implement the Comparable module and respond to
+      # the <=> operator.
+      #
+      # @example Basic ordering validation
+      #   constraint = OrderingConstraint.new(:self)
+      #   constraint.satisfied?([1, 2, 3])     # => true
+      #   constraint.satisfied?([1, 3, 2])     # => false
+      #
+      # @example With string elements
+      #   constraint = OrderingConstraint.new(:self)
+      #   constraint.satisfied?(['a', 'b', 'c']) # => true
+      #   constraint.satisfied?(['c', 'a', 'b']) # => false
+      #
+      # @example With mixed types that can be compared
+      #   constraint = OrderingConstraint.new(:self)
+      #   constraint.satisfied?([1, 1.5, 2])     # => true
+      #   constraint.satisfied?([2, 1, 1.5])     # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class OrderingConstraint
+        include Behavior[nil, untyped, { }]
+
+        # Get a human-readable description of the ordering requirement.
+        #
+        # @example
+        #   constraint = OrderingConstraint.new(:self)
+        #   constraint.description # => "ordered"
+        #
+        # @return [String] A description of the ordering requirement
+        def short_description: ...
+
+        # Get a human-readable description of why ordering validation failed.
+        #
+        # @example
+        #   constraint = OrderingConstraint.new(:self)
+        #   constraint.satisfied?([3, 1, 2])
+        #   constraint.short_violation_description # => "not ordered"
+        #
+        # @return [String] A description of the ordering failure
+        def short_violation_description: ...
+
+        # Check if the collection elements are in sorted order.
+        #
+        # Compares the collection to its sorted version to determine if the
+        # elements are already in ascending order.
+        #
+        # @return [Boolean] true if the elements are in sorted order
+        def satisfies_constraint?: ...
+      end
+    end
+  end
+end

data/sig/domainic/type/constraint/constraints/parity_constraint.rbs

@@ -0,0 +1,71 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating numeric parity (even or odd).
+      #
+      # This constraint verifies a number's parity by calling Ruby's standard
+      # even? and odd? methods. It normalizes method names
+      # to ensure compatibility with Ruby's predicate method naming conventions.
+      #
+      # @example Basic polarity checks
+      #   constraint = ParityConstraint.new(:self).expecting(:even)
+      #   constraint.satisfied?(2)   # => true
+      #   constraint.satisfied?(-2)  # => true
+      #   constraint.satisfied?(1)    # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class ParityConstraint
+        type expected = :even | :even? | :odd | :odd?
+
+        include Behavior[expected, Numeric, { }]
+
+        # Get a human-readable description of the parity requirement.
+        #
+        # @example
+        #   constraint = ParityConstraint.new(:self).expecting(:even)
+        #   constraint.short_description  # => "even"
+        #
+        # @return [String] Description of the parity requirement
+        def short_description: ...
+
+        # Get a human-readable description of why parity validation failed.
+        #
+        # @example
+        #   constraint = ParityConstraint.new(:self).expecting(:positive)
+        #   constraint.satisfied?(0)
+        #   constraint.short_violation_description  # => "odd"
+        #
+        # @return [String] Description of the validation failure
+        def short_violation_description: ...
+
+        # Coerce the expectation into the correct method name format.
+        #
+        # Ensures the expectation ends with a question mark to match Ruby's
+        # standard method naming for predicate methods.
+        #
+        # @example
+        #   coerce_expectation(:even)   # => :even?
+        #   coerce_expectation(:even?)  # => :eve?
+        #
+        # @param expectation [Symbol, String] The parity check to perform
+        #
+        # @return [Symbol] The coerced method name
+        def coerce_expectation: ...
+
+        # Check if the value satisfies the parity constraint.
+        #
+        # @return [Boolean] true if the value matches the parity requirement
+        def satisfies_constraint?: ...
+
+        # Validate that the expectation is a valid parity check.
+        #
+        # @param expectation [Object] The value to validate
+        #
+        # @raise [ArgumentError] if the expectation is not :even, :even?, :odd, or :odd?
+        # @return [void]
+        def validate_expectation!: ...
+      end
+    end
+  end
+end

data/sig/domainic/type/constraint/constraints/polarity_constraint.rbs

@@ -0,0 +1,101 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating numeric polarity (positive, negative, zero, nonzero).
+      #
+      # This constraint verifies a number's polarity by calling Ruby's standard
+      # positive?, negative?, zero?, and nonzero? methods. It normalizes method names
+      # to ensure compatibility with Ruby's predicate method naming conventions.
+      #
+      # @example Basic polarity checks
+      #   constraint = PolarityConstraint.new(:self).expecting(:positive)
+      #   constraint.satisfied?(42)   # => true
+      #   constraint.satisfied?(-42)  # => false
+      #   constraint.satisfied?(0)    # => false
+      #
+      # @example Zero checks
+      #   constraint = PolarityConstraint.new(:self).expecting(:zero)
+      #   constraint.satisfied?(0)    # => true
+      #   constraint.satisfied?(42)   # => false
+      #
+      # @example Nonzero checks
+      #   constraint = PolarityConstraint.new(:self).expecting(:nonzero)
+      #   constraint.satisfied?(42)   # => true
+      #   constraint.satisfied?(0)    # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class PolarityConstraint
+        type expected = :negative | :negative? | :nonzero | :nonzero? | :positive | :positive? | :zero | :zero?
+
+        include Behavior[expected, Numeric, { }]
+
+        # Get a human-readable description of the polarity requirement.
+        #
+        # @example
+        #   constraint = PolarityConstraint.new(:self).expecting(:positive)
+        #   constraint.short_description  # => "positive"
+        #
+        # @return [String] Description of the polarity requirement
+        def short_description: ...
+
+        # Get a human-readable description of why polarity validation failed.
+        #
+        # @example
+        #   constraint = PolarityConstraint.new(:self).expecting(:positive)
+        #   constraint.satisfied?(0)
+        #   constraint.short_violation_description  # => "zero"
+        #
+        # @return [String] Description of the validation failure
+        def short_violation_description: ...
+
+        # Coerce the expectation into the correct method name format.
+        #
+        # Ensures the expectation ends with a question mark to match Ruby's
+        # standard method naming for predicate methods.
+        #
+        # @example
+        #   coerce_expectation(:positive)   # => :positive?
+        #   coerce_expectation(:positive?)  # => :positive?
+        #
+        # @param expectation [Symbol, String] The polarity check to perform
+        #
+        # @return [Symbol] The coerced method name
+        def coerce_expectation: ...
+
+        # Check if the value satisfies the polarity constraint.
+        #
+        # @return [Boolean] true if the value matches the polarity requirement
+        def satisfies_constraint?: ...
+
+        # Validate that the expectation is a valid polarity check.
+        #
+        # @param expectation [Object] The value to validate
+        #
+        # @raise [ArgumentError] if the expectation is not :negative, :negative?, :nonzero,
+        #   :nonzero?, :positive, :positive?, :zero, or :zero?
+        # @return [void]
+        def validate_expectation!: ...
+
+        private
+
+        # Interpret the result from Ruby's polarity methods.
+        #
+        # Handles the different return values from Ruby's polarity checking methods:
+        # - positive?/negative?/zero? return true/false
+        # - nonzero? returns nil for zero, and self for nonzero
+        #
+        # @example
+        #   interpret_result(true)   # => true
+        #   interpret_result(false)  # => false
+        #   interpret_result(nil)    # => false
+        #   interpret_result(42)     # => true
+        #
+        # @param result [Boolean, Integer, nil] The result from the polarity check
+        #
+        # @return [Boolean] true if the result indicates the desired polarity state
+        def interpret_result: ((bool | Numeric)? result) -> bool
+      end
+    end
+  end
+end

data/sig/domainic/type/constraint/constraints/range_constraint.rbs

@@ -0,0 +1,88 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating that numeric values fall within a specified range.
+      #
+      # This constraint allows for validating numeric values against minimum and maximum
+      # boundaries. It supports specifying either or both boundaries, allowing for
+      # open-ended ranges when appropriate.
+      #
+      # @example Validating with both minimum and maximum
+      #   constraint = RangeConstraint.new(:self, { minimum: 1, maximum: 10 })
+      #   constraint.satisfied?(5)  # => true
+      #   constraint.satisfied?(15) # => false
+      #
+      # @example Validating with only minimum
+      #   constraint = RangeConstraint.new(:self, { minimum: 0 })
+      #   constraint.satisfied?(10)  # => true
+      #   constraint.satisfied?(-1)  # => false
+      #
+      # @example Validating with only maximum
+      #   constraint = RangeConstraint.new(:self, { maximum: 100 })
+      #   constraint.satisfied?(50)   # => true
+      #   constraint.satisfied?(150)  # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class RangeConstraint
+        type expected = { ?minimum: Numeric, ?maximum: Numeric }
+
+        type options = { ?inclusive: bool }
+
+        include Behavior[expected, Numeric, options]
+
+        # Get a human-readable description of the range constraint.
+        #
+        # @example With both bounds
+        #   constraint = RangeConstraint.new(:self, { minimum: 1, maximum: 10 })
+        #   constraint.description
+        #   # => "greater than or equal to 1 and less than or equal to 10"
+        #
+        # @example With only minimum
+        #   constraint = RangeConstraint.new(:self, { minimum: 0 })
+        #   constraint.description # => "greater than or equal to 0"
+        #
+        # @example With only maximum
+        #   constraint = RangeConstraint.new(:self, { maximum: 100 })
+        #   constraint.description # => "less than or equal to 100"
+        #
+        # @return [String] A description of the range bounds
+        def short_description: ...
+
+        # The description of the violations that caused the constraint to be unsatisfied.
+        #
+        # This is used to help compose a error message when the constraint is not satisfied.
+        # Implementing classes can override this to provide more specific failure messages.
+        #
+        # @return [String] The description of the constraint when it fails.
+        def short_violation_description: ...
+
+        def coerce_expectation: ...
+
+        # Check if the actual value falls within the specified range.
+        #
+        # Uses -Infinity and +Infinity as default bounds when minimum or maximum
+        # are not specified, respectively.
+        #
+        # @return [Boolean] true if the value is within range
+        def satisfies_constraint?: ...
+
+        # Validate that the expected value is a properly formatted range specification.
+        #
+        # @param expectation [Hash] The range specification to validate
+        #
+        # @raise [ArgumentError] if the specification is invalid
+        # @return [void]
+        def validate_expectation!: ...
+
+        # Validate the minimum and maximum values in a range specification.
+        #
+        # @param expectation [Hash] The range specification to validate
+        #
+        # @raise [ArgumentError] if the values are invalid
+        # @return [void]
+        def validate_minimum_and_maximum!: (untyped expectation) -> void
+      end
+    end
+  end
+end

data/sig/domainic/type/constraint/constraints/type_constraint.rbs

@@ -0,0 +1,86 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating that values match a specific type.
+      #
+      # This constraint provides type checking functionality through Ruby's standard
+      # type system, supporting class inheritance checks, module inclusion checks,
+      # and custom type validation through the case equality operator (===).
+      #
+      # @example Basic class type validation
+      #   constraint = TypeConstraint.new(:self, String)
+      #   constraint.satisfied?("hello") # => true
+      #   constraint.satisfied?(123)     # => false
+      #
+      # @example Module type validation
+      #   constraint = TypeConstraint.new(:self, Enumerable)
+      #   constraint.satisfied?([1, 2, 3]) # => true
+      #   constraint.satisfied?("string")   # => false
+      #
+      # @example Custom type validation
+      #   class EvenType
+      #     def self.===(value)
+      #       value.is_a?(Integer) && value.even?
+      #     end
+      #   end
+      #
+      #   constraint = TypeConstraint.new(:self, EvenType)
+      #   constraint.satisfied?(2)  # => true
+      #   constraint.satisfied?(3)  # => false
+      #
+      # @example Nil type validation
+      #   constraint = TypeConstraint.new(:self, nil)
+      #   constraint.satisfied?(nil)   # => true
+      #   constraint.satisfied?(false) # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class TypeConstraint
+        include Behavior[Class | Module | Type::Behavior | nil, untyped, { }]
+
+        # Get a human-readable description of the expected type.
+        #
+        # @example
+        #   constraint = TypeConstraint.new(:self, Float)
+        #   constraint.description # => "Float"
+        #
+        #   constraint = TypeConstraint.new(:self, Array)
+        #   constraint.description # => "Array"
+        #
+        # @return [String] A description of the expected type
+        def short_description: ...
+
+        # The description of the violations that caused the constraint to be unsatisfied.
+        #
+        # This is used to help compose a error message when the constraint is not satisfied.
+        # Implementing classes can override this to provide more specific failure messages.
+        #
+        # @return [String] The description of the constraint when it fails.
+        def short_violation_description: ...
+
+        # Coerce the expected type, converting nil to NilClass for type checking.
+        #
+        # @param expectation [Class, Module, nil] The type to coerce
+        #
+        # @return [Class, Module] The coerced type
+        def coerce_expectation: ...
+
+        # Check if the actual value matches the expected type.
+        #
+        # The check is performed using both the case equality operator (===)
+        # and Ruby's is_a? method to provide maximum flexibility in type checking.
+        #
+        # @return [Boolean] true if the value matches the expected type
+        def satisfies_constraint?: ...
+
+        # Validate that the expected type is a valid Ruby type.
+        #
+        # @param expectation [Object] The type to validate
+        #
+        # @raise [ArgumentError] if the expectation is not a valid type
+        # @return [void]
+        def validate_expectation!: ...
+      end
+    end
+  end
+end

data/sig/domainic/type/constraint/constraints/uniqueness_constraint.rbs

@@ -0,0 +1,54 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating that all elements in a collection are unique.
+      #
+      # This constraint ensures that an enumerable collection contains no duplicate
+      # elements by comparing the collection's size before and after removing duplicates.
+      # It works with any object that includes the Enumerable module and responds
+      # to #uniq and #count.
+      #
+      # @example Basic uniqueness validation
+      #   constraint = UniquenessConstraint.new(:self)
+      #   constraint.satisfied?([1, 2, 3])     # => true
+      #   constraint.satisfied?([1, 2, 2, 3])  # => false
+      #
+      # @example With different collection types
+      #   constraint = UniquenessConstraint.new(:self)
+      #   constraint.satisfied?(Set[1, 2, 3])        # => true
+      #   constraint.satisfied?(['a', 'b', 'b'])     # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class UniquenessConstraint
+        include Behavior[nil, Enumerable, { }]
+
+        # Get a human-readable description of the uniqueness requirement.
+        #
+        # @example
+        #   constraint = UniquenessConstraint.new(:self)
+        #   constraint.description # => "unique"
+        #
+        # @return [String] A description of the uniqueness requirement
+        def short_description: ...
+
+        # The description of the violations that caused the constraint to be unsatisfied.
+        #
+        # This is used to help compose a error message when the constraint is not satisfied.
+        # Implementing classes can override this to provide more specific failure messages.
+        #
+        # @return [String] The description of the constraint when it fails.
+        def short_violation_description: ...
+
+        # Check if all elements in the collection are unique.
+        #
+        # Compares the size of the collection before and after removing duplicates.
+        # If the sizes are equal, all elements are unique. If they differ, duplicates
+        # were present.
+        #
+        # @return [Boolean] true if all elements are unique
+        def satisfies_constraint?: ...
+      end
+    end
+  end
+end

data/sig/domainic/type/constraint/resolver.rbs

@@ -0,0 +1,117 @@
+module Domainic
+  module Type
+    module Constraint
+      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
+        type registry_constraint = { constant: String, require_path: String }
+
+        @file_name: String
+
+        @constraint_type: Symbol
+
+        @constant_name: String
+
+        self.@registry: Hash[Symbol, Hash[Symbol, registry_constraint]]
+
+        # 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]
+        def self.register_constraint: (String | Symbol lookup_key, String constant_name, String require_path) -> void
+
+        # 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
+        def self.resolve!: (Symbol constraint_type) -> _ConstraintClass
+
+        # The registry of known constraints
+        #
+        # @return [Hash{Symbol => Hash{Symbol => String}}] The constraint registry
+        private def self.registry: () -> Hash[Symbol, registry_constraint]
+
+        # Initialize a new Resolver instance.
+        #
+        # @param constraint_type [Symbol] The type of constraint to resolve
+        #
+        # @return [void]
+        def initialize: (String | Symbol constraint_type) -> void
+
+        # 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
+        def resolve!: () -> _ConstraintClass
+
+        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
+        def constraint_class: () -> _ConstraintClass
+
+        # 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]
+        def load_constraint!: () -> void
+
+        # Fetch the registered constraint from the registry
+        #
+        # @return [Hash{Symbol => String}] The registered constraint
+        def registered: () -> registry_constraint?
+      end
+    end
+  end
+end