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

data/lib/domainic/type/constraint/constraints/parity_constraint.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+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
+        # @rbs!
+        #   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
+        # @rbs override
+        def short_description
+          @expected.to_s.delete_suffix('?')
+        end
+
+        # 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
+        # @rbs override
+        def short_violation_description
+          case @expected
+          when :even?
+            'odd'
+          when :odd?
+            'even'
+          else
+            ''
+          end
+        end
+
+        protected
+
+        # 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
+        # @rbs override
+        def coerce_expectation(expectation)
+          expectation.to_s.end_with?('?') ? expectation.to_sym : :"#{expectation}?" #: expected
+        end
+
+        # Check if the value satisfies the parity constraint.
+        #
+        # @return [Boolean] true if the value matches the parity requirement
+        # @rbs override
+        def satisfies_constraint?
+          @actual.public_send(@expected)
+        end
+
+        # 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]
+        # @rbs override
+        def validate_expectation!(expectation)
+          return if %i[even? odd?].include?(expectation)
+
+          raise ArgumentError, "Invalid expectation: #{expectation}. Must be one of :even, :even?, :odd, or :odd?"
+        end
+      end
+    end
+  end
+end

data/lib/domainic/type/constraint/constraints/polarity_constraint.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+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
+        # @rbs!
+        #   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
+        # @rbs override
+        def short_description
+          @expected.to_s.delete_suffix('?')
+        end
+
+        # 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
+        # @rbs override
+        def short_violation_description # rubocop:disable Metrics/MethodLength
+          case @expected
+          when :positive?
+            @actual.zero? ? 'zero' : 'negative'
+          when :negative?
+            @actual.zero? ? 'zero' : 'positive'
+          when :zero?
+            'nonzero'
+          when :nonzero?
+            'zero'
+          else
+            ''
+          end
+        end
+
+        protected
+
+        # 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
+        # @rbs override
+        def coerce_expectation(expectation)
+          expectation.to_s.end_with?('?') ? expectation.to_sym : :"#{expectation}?" #: expected
+        end
+
+        # Check if the value satisfies the polarity constraint.
+        #
+        # @return [Boolean] true if the value matches the polarity requirement
+        # @rbs override
+        def satisfies_constraint?
+          interpret_result(@actual.public_send(@expected))
+        end
+
+        # 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]
+        # @rbs override
+        def validate_expectation!(expectation)
+          return if %i[negative? nonzero? positive? zero?].include?(expectation)
+
+          raise ArgumentError, "Invalid expectation: #{expectation}. Must be one of :negative, :negative?, :nonzero, " \
+                               ':nonzero?, :positive, :positive?, :zero, or :zero?'
+        end
+
+        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
+        # @rbs ((bool | Numeric)? result) -> bool
+        def interpret_result(result)
+          case result
+          when true, false
+            result
+          when nil
+            false
+          else
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/domainic/type/constraint/constraints/range_constraint.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+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
+        # @rbs!
+        #   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
+        # @rbs override
+        def short_description
+          min, max = @expected.values_at(:minimum, :maximum)
+          min_description = "greater than or equal to #{min}"
+          max_description = "less than or equal to #{max}"
+
+          return "#{min_description} and #{max_description}" unless min.nil? || max.nil?
+          return min_description unless min.nil?
+
+          max_description
+        end
+
+        # 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.
+        # @rbs override
+        def short_violation_description
+          @actual.inspect
+        end
+
+        protected
+
+        # @rbs override
+        def coerce_expectation(expectation)
+          @expected.is_a?(Hash) && expectation.is_a?(Hash) ? @expected.merge(expectation) : expectation #: expected
+        end
+
+        # 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
+        # @rbs override
+        def satisfies_constraint?
+          min, max = @expected.values_at(:minimum, :maximum)
+          min_comparison, max_comparison = @options.fetch(:inclusive, true) ? %i[>= <=] : %i[> <]
+
+          @actual.send(min_comparison, (min || -Float::INFINITY)) &&
+            @actual.send(max_comparison, (max || Float::INFINITY))
+        end
+
+        # 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]
+        # @rbs override
+        def validate_expectation!(expectation)
+          unless expectation.is_a?(Hash) && (expectation.key?(:minimum) || expectation.key?(:maximum))
+            raise ArgumentError, 'Expectation must be a Hash including :minimum and/or :maximum'
+          end
+
+          validate_minimum_and_maximum!(expectation)
+        end
+
+        # 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]
+        # @rbs (untyped expectation) -> void
+        def validate_minimum_and_maximum!(expectation)
+          expectation.each_pair do |property, value|
+            raise ArgumentError, ":#{property} must be a Numeric" unless value.nil? || value.is_a?(Numeric)
+          end
+
+          min, max = expectation.values_at(:minimum, :maximum)
+          return if min.nil? || max.nil? || min <= max
+
+          raise ArgumentError, ':minimum must be less than or equal to :maximum'
+        end
+      end
+    end
+  end
+end

data/lib/domainic/type/constraint/constraints/type_constraint.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+require 'domainic/type/constraint/behavior'
+
+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
+        # @rbs override
+        def short_description
+          @expected.to_s
+        end
+
+        # 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.
+        # @rbs override
+        def short_violation_description
+          @actual.class.to_s
+        end
+
+        protected
+
+        # 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
+        # @rbs override
+        def coerce_expectation(expectation)
+          expectation.nil? ? NilClass : expectation
+        end
+
+        # 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
+        # @rbs override
+        def satisfies_constraint?
+          @expected === @actual || @actual.is_a?(@expected) # rubocop:disable Style/CaseEquality
+        end
+
+        # 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]
+        # @rbs override
+        def validate_expectation!(expectation)
+          return if [Class, Module, Type::Behavior].any? { |type| expectation.is_a?(type) }
+
+          raise ArgumentError, 'Expectation must be a Class, Module, or Domainic::Type'
+        end
+      end
+    end
+  end
+end

data/lib/domainic/type/constraint/constraints/uniqueness_constraint.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+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
+        # @rbs override
+        def short_description
+          'unique'
+        end
+
+        # 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.
+        # @rbs override
+        def short_violation_description
+          'not unique'
+        end
+
+        protected
+
+        # 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
+        # @rbs override
+        def satisfies_constraint?
+          @actual.uniq.count == @actual.count
+        end
+      end
+    end
+  end
+end