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

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

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+module Domainic
+  module Type
+    module Constraint
+      # A constraint that ensures any element in an enumerable satisfies a given constraint.
+      #
+      # The AnyConstraint validates that at least one element in an enumerable value meets
+      # the provided constraint. This enables validation rules like "must contain at least
+      # one string" or "must have any positive number".
+      #
+      # Key features:
+      # - Validates enumerable elements against a constraint
+      # - Short-circuits on first satisfying element
+      # - Provides clear error messages for failing elements
+      # - Handles non-enumerable values gracefully
+      #
+      # @example Validating an array contains any string
+      #   string_constraint = StringConstraint.new(:self)
+      #   any_string = AnyConstraint.new(:self, string_constraint)
+      #
+      #   any_string.satisfied?(['a', 1, 'c'])  # => true
+      #   any_string.satisfied?([1, 2, 3])      # => false
+      #   any_string.satisfied?(nil)            # => false (not enumerable)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class AnyConstraint
+        include Behavior #[Behavior[untyped, untyped, untyped], Enumerable, {}]
+
+        # Get a description of what the constraint expects.
+        #
+        # @return [String] a description combining all constraint descriptions
+        # @rbs override
+        def short_description
+          @expected.short_description
+        end
+
+        # The description of the violations that caused the constraint to be unsatisfied.
+        #
+        # This method provides detailed feedback when no constraints are satisfied,
+        # listing all the ways in which the value failed validation.
+        #
+        # @return [String] The combined violation descriptions from all constraints
+        # @rbs override
+        def short_violation_description
+          return 'not Enumerable' unless @actual.is_a?(Enumerable) # steep:ignore NoMethod
+
+          @actual.filter_map do |element|
+            next if @expected.satisfied?(element)
+
+            @expected.short_violation_description
+          end.uniq.join(', ')
+        end
+
+        protected
+
+        # Check if the value satisfies any of the expected constraints.
+        #
+        # @return [Boolean] whether any constraint is satisfied
+        # @rbs override
+        def satisfies_constraint?
+          @actual.any? { |element| @expected.satisfied?(element) }
+        end
+
+        # Validate that the expectation is an array of valid constraints.
+        #
+        # @param expectation [Object] the expectation to validate
+        #
+        # @raise [ArgumentError] if the expectation is not valid
+        # @return [void]
+        # @rbs override
+        def validate_expectation!(expectation)
+          return if expectation.is_a?(Behavior)
+
+          raise ArgumentError, "expected a Domainic::Type::Constraint, got #{expectation.class}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating string case formatting.
+      #
+      # This constraint verifies that string values conform to specific case formats:
+      # - upper: all characters are uppercase
+      # - lower: all characters are lowercase
+      # - mixed: contains both uppercase and lowercase characters
+      # - title: words are capitalized (first letter uppercase, rest lowercase)
+      #
+      # @example Uppercase validation
+      #   constraint = CaseConstraint.new(:self, :upper)
+      #   constraint.satisfied?("HELLO")  # => true
+      #   constraint.satisfied?("Hello")  # => false
+      #
+      # @example Title case validation
+      #   constraint = CaseConstraint.new(:self, :title)
+      #   constraint.satisfied?("Hello World")  # => true
+      #   constraint.satisfied?("hello world")  # => false
+      #
+      # @example Mixed case validation
+      #   constraint = CaseConstraint.new(:self, :mixed)
+      #   constraint.satisfied?("helloWORLD")  # => true
+      #   constraint.satisfied?("HELLO")      # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class CaseConstraint
+        # @rbs!
+        #   type expected = :upper | :lower | :mixed | :title
+
+        include Behavior #[expected, untyped, {}]
+
+        # Valid case format options
+        #
+        # @return [Array<Symbol>] List of valid case formats
+        VALID_CASES = %i[upper lower mixed title].freeze #: Array[expected]
+
+        # Get a human-readable description of the case requirement.
+        #
+        # @example
+        #   constraint = CaseConstraint.new(:self, :upper)
+        #   constraint.short_description # => "upper case"
+        #
+        # @return [String] A description of the case requirement
+        # @rbs override
+        def short_description
+          "#{@expected} case"
+        end
+
+        # Get a human-readable description of why case validation failed.
+        #
+        # @example
+        #   constraint = CaseConstraint.new(:self, :upper)
+        #   constraint.satisfied?("Hello")
+        #   constraint.short_violation_description # => "not upper case"
+        #
+        # @return [String] A description of the case mismatch
+        # @rbs override
+        def short_violation_description
+          "not #{@expected} case"
+        end
+
+        protected
+
+        # Check if the string matches the expected case format.
+        #
+        # @return [Boolean] true if the string matches the expected case
+        # @rbs override
+        def satisfies_constraint?
+          case @expected
+          when :upper
+            @actual == @actual.upcase
+          when :lower
+            @actual == @actual.downcase
+          when :title
+            # Use map and join to preserve original whitespace
+            @actual == @actual.scan(/[^\s]+/).map(&:capitalize).join(
+              @actual.match(/\s+/).to_s
+            )
+          when :mixed
+            !(@actual == @actual.upcase || @actual == @actual.downcase)
+          end
+        end
+
+        # Validate that the expectation is a valid case format.
+        #
+        # @param expectation [Object] The case format to validate
+        #
+        # @raise [ArgumentError] if the expectation is not a valid case format
+        # @return [void]
+        # @rbs override
+        def validate_expectation!(expectation)
+          raise ArgumentError, "case must be one of: #{VALID_CASES.join(', ')}" unless VALID_CASES.include?(expectation)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating string character sets.
+      #
+      # This constraint verifies that string values contain only characters from
+      # specific character sets:
+      # - ascii: ASCII characters (0x00-0x7F)
+      # - alphanumeric: Letters and numbers
+      # - alpha: Letters only
+      # - numeric: Numbers only
+      # - printable: Visible characters and spaces
+      #
+      # @example ASCII validation
+      #   constraint = CharacterSetConstraint.new(:self, :ascii)
+      #   constraint.satisfied?("hello")  # => true
+      #   constraint.satisfied?("héllo")  # => false
+      #
+      # @example Alphanumeric validation
+      #   constraint = CharacterSetConstraint.new(:self, :alphanumeric)
+      #   constraint.satisfied?("abc123")  # => true
+      #   constraint.satisfied?("abc-123") # => false
+      #
+      # @example Numeric validation
+      #   constraint = CharacterSetConstraint.new(:self, :numeric)
+      #   constraint.satisfied?("12345")   # => true
+      #   constraint.satisfied?("123.45")  # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class CharacterSetConstraint
+        # @rbs!
+        #   type expected = :ascii | :alphanumeric | :alpha | :numeric | :printable
+
+        include Behavior #[expected, untyped, {}]
+
+        # Valid character set patterns
+        #
+        # @return [Hash{Symbol => Regexp}] Map of set names to validation patterns
+        VALID_SETS = {
+          ascii: /\A[\x00-\x7F]*\z/, # Any ASCII character
+          alphanumeric: /\A[[:alnum:]]*\z/,   # Letters and numbers
+          alpha: /\A[[:alpha:]]*\z/,          # Letters only
+          numeric: /\A[[:digit:]]*\z/,        # Numbers only
+          printable: /\A[[:print:]]*\z/       # Visible chars and spaces
+        }.freeze #: Hash[expected, Regexp]
+
+        # Get a human-readable description of the character set requirement.
+        #
+        # @example
+        #   constraint = CharacterSetConstraint.new(:self, :numeric)
+        #   constraint.short_description # => "only numeric characters"
+        #
+        # @return [String] A description of the character set requirement
+        # @rbs override
+        def short_description
+          "only #{@expected} characters"
+        end
+
+        # Get a human-readable description of why character validation failed.
+        #
+        # @example
+        #   constraint = CharacterSetConstraint.new(:self, :numeric)
+        #   constraint.satisfied?("abc123")
+        #   constraint.short_violation_description # => "non-numeric characters"
+        #
+        # @return [String] A description of the character set violation
+        # @rbs override
+        def short_violation_description
+          "non-#{@expected} characters"
+        end
+
+        protected
+
+        # Convert character set name to symbol.
+        #
+        # @param expectation [String, Symbol] The character set name
+        #
+        # @return [Symbol] The character set name as a symbol
+        # @rbs override
+        def coerce_expectation(expectation)
+          expectation.to_sym
+        end
+
+        # Check if the string contains only characters from the expected set.
+        #
+        # @return [Boolean] true if all characters match the expected set
+        # @rbs override
+        def satisfies_constraint?
+          pattern = VALID_SETS.fetch(@expected)
+          pattern.match?(@actual)
+        end
+
+        # Validate that the expectation is a valid character set.
+        #
+        # @param expectation [Object] The character set to validate
+        #
+        # @raise [ArgumentError] if the expectation is not a valid character set
+        # @return [void]
+        # @rbs override
+        def validate_expectation!(expectation)
+          raise ArgumentError, "set must be one of: #{VALID_SETS.keys.join(', ')}" unless VALID_SETS.key?(expectation)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating that numeric values are divisible by a specified value.
+      #
+      # This constraint checks if one number is evenly divisible by another, allowing for
+      # a configurable tolerance to handle floating-point arithmetic imprecision. It can
+      # be used to validate properties like:
+      # - Even/odd numbers (divisible by 2)
+      # - Factors and multiples
+      # - Decimal place alignment (divisible by 0.1, 0.01, etc)
+      #
+      # @example Basic divisibility check
+      #   constraint = DivisibilityConstraint.new(:self, 5)
+      #   constraint.satisfied?(10)  # => true
+      #   constraint.satisfied?(7)   # => false
+      #
+      # @example With floating point values
+      #   constraint = DivisibilityConstraint.new(:self, 0.1)
+      #   constraint.satisfied?(0.3)  # => true
+      #   constraint.satisfied?(0.35) # => false
+      #
+      # @example Custom tolerance
+      #   constraint = DivisibilityConstraint.new(:self)
+      #   constraint.expecting(3)
+      #   constraint.with_options(tolerance: 1e-5)
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class DivisibilityConstraint
+        # @rbs!
+        #   type options = { ?tolerance: Numeric }
+
+        include Behavior #[Numeric, Numeric, options]
+
+        # Default tolerance for floating-point arithmetic comparisons.
+        #
+        # @return [Float] The default tolerance value
+        DEFAULT_TOLERANCE = 1e-10 #: Float
+
+        # Get a human-readable description of the divisibility requirement.
+        #
+        # @example
+        #   constraint = DivisibilityConstraint.new(:self, 5)
+        #   constraint.short_description # => "divisible by 5"
+        #
+        # @return [String] Description of the divisibility requirement
+        # @rbs override
+        def short_description
+          "divisible by #{@expected.inspect}"
+        end
+
+        # Get a human-readable description of why divisibility validation failed.
+        #
+        # @example With non-numeric value
+        #   constraint = DivisibilityConstraint.new(:self, 5)
+        #   constraint.satisfied?("not a number")
+        #   constraint.short_violation_description # => "not Numeric"
+        #
+        # @example With non-divisible value
+        #   constraint = DivisibilityConstraint.new(:self, 5)
+        #   constraint.satisfied?(7)
+        #   constraint.short_violation_description # => "not divisible by 5"
+        #
+        # @return [String] Description of the validation failure
+        # @rbs override
+        def short_violation_description
+          return 'not Numeric' unless @actual.is_a?(Numeric)
+
+          "not divisible by #{@expected.inspect}"
+        end
+
+        protected
+
+        # Check if the actual value is evenly divisible by the expected value.
+        #
+        # This method handles both integer and floating-point values, using the
+        # configured tolerance to account for floating-point arithmetic imprecision.
+        #
+        # @return [Boolean] true if the value is evenly divisible
+        # @rbs override
+        def satisfies_constraint?
+          actual = parse_value(@actual)
+          expected = parse_value(@expected)
+
+          return false if actual.nil? || expected.nil?
+          return false if expected.zero?
+
+          tolerance = @options.fetch(:tolerance, DEFAULT_TOLERANCE)
+          # @type var tolerance: Numeric
+          ((actual / expected) - (actual / expected).round).abs < tolerance
+        end
+
+        # Validate that the expected value is a non-zero number.
+        #
+        # @param expectation [Object] The value to validate
+        #
+        # @raise [ArgumentError] if the value is not a non-zero number
+        # @return [void]
+        # @rbs override
+        def validate_expectation!(expectation)
+          raise ArgumentError, 'Expectation must be Numeric' unless expectation.is_a?(Numeric)
+          raise ArgumentError, 'Expectation must be non-zero' if expectation.zero?
+        end
+
+        private
+
+        # Parse a value into a float, returning nil if parsing fails.
+        #
+        # @param value [Numeric] The value to parse
+        #
+        # @return [Float, nil] The parsed float value or nil if parsing failed
+        # @rbs (Numeric value) -> Float?
+        def parse_value(value)
+          Float(value)
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/domainic/type/constraint/constraints/emptiness_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 a collection is empty.
+      #
+      # This constraint ensures that an enumerable collection contains no elements
+      # by checking the collection's #empty? method. It works with any object that
+      # includes the Enumerable module and responds to #empty?.
+      #
+      # @example Basic emptiness validation
+      #   constraint = EmptinessConstraint.new(:self)
+      #   constraint.satisfied?([])        # => true
+      #   constraint.satisfied?([1, 2, 3]) # => false
+      #
+      # @example With different collection types
+      #   constraint = EmptinessConstraint.new(:self)
+      #   constraint.satisfied?(Set.new)    # => true
+      #   constraint.satisfied?(['a', 'b']) # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class EmptinessConstraint
+        include Behavior #[nil, untyped, {}]
+
+        # Get a human-readable description of the emptiness requirement.
+        #
+        # @example
+        #   constraint = EmptinessConstraint.new(:self)
+        #   constraint.description # => "empty"
+        #
+        # @return [String] A description of the emptiness requirement
+        # @rbs override
+        def short_description
+          'empty'
+        end
+
+        # Get a human-readable description of why emptiness validation failed.
+        #
+        # @example
+        #   constraint = EmptinessConstraint.new(:self)
+        #   constraint.satisfied?([1, 2, 3])
+        #   constraint.short_violation_description # => "not empty"
+        #
+        # @return [String] A description of the emptiness failure
+        # @rbs override
+        def short_violation_description
+          'not empty'
+        end
+
+        protected
+
+        # Check if the collection is empty.
+        #
+        # Uses the collection's #empty? method to determine if it contains
+        # any elements.
+        #
+        # @return [Boolean] true if the collection is empty
+        # @rbs override
+        def satisfies_constraint?
+          @actual.empty?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating that values are equal to an expected value.
+      #
+      # This constraint uses Ruby's standard equality operator (==) to compare values,
+      # allowing for type-specific equality definitions while maintaining consistent
+      # behavior across different value types.
+      #
+      # @example Basic equality validation
+      #   constraint = EqualityConstraint.new(:self, 42)
+      #   constraint.satisfied?(42)    # => true
+      #   constraint.satisfied?(41)    # => false
+      #
+      # @example Complex object comparison
+      #   point = Struct.new(:x, :y).new(1, 2)
+      #   constraint = EqualityConstraint.new(:self, point)
+      #   constraint.satisfied?(Struct.new(:x, :y).new(1, 2)) # => true
+      #   constraint.satisfied?(Struct.new(:x, :y).new(2, 1)) # => false
+      #
+      # @example Array comparison
+      #   constraint = EqualityConstraint.new(:self, [1, 2, 3])
+      #   constraint.satisfied?([1, 2, 3]) # => true
+      #   constraint.satisfied?([3, 2, 1]) # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class EqualityConstraint
+        include Behavior #[untyped, untyped, {}]
+
+        # Get a human-readable description of the equality requirement.
+        #
+        # @example
+        #   constraint = EqualityConstraint.new(:self, 42)
+        #   constraint.description # => "equal to 42"
+        #
+        # @return [String] A description of the expected value
+        # @rbs override
+        def short_description
+          "equal to #{@expected.inspect}"
+        end
+
+        # Get a human-readable description of why equality validation failed.
+        #
+        # @example
+        #   constraint = EqualityConstraint.new(:self, 42)
+        #   constraint.satisfied?(41)
+        #   constraint.short_violation_description # => "not equal to 42"
+        #
+        # @return [String] A description of the equality failure
+        # @rbs override
+        def short_violation_description
+          "not equal to #{@expected.inspect}"
+        end
+
+        protected
+
+        # Check if the actual value equals the expected value.
+        #
+        # Uses Ruby's standard equality operator (==) for comparison, allowing
+        # objects to define their own equality behavior.
+        #
+        # @return [Boolean] true if the values are equal
+        # @rbs override
+        def satisfies_constraint?
+          @actual == @expected
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+module Domainic
+  module Type
+    module Constraint
+      # A constraint for validating that numeric values are finite or infinite.
+      #
+      # This constraint verifies whether a numeric value is finite or infinite by calling
+      # Ruby's standard finite?/infinite? methods. It's useful for ensuring numbers remain
+      # within computable bounds and handling edge cases in numerical computations.
+      #
+      # @example Basic finiteness check
+      #   constraint = FinitenessConstraint.new(:self).expecting(:finite)
+      #   constraint.satisfied?(42)      # => true
+      #   constraint.satisfied?(Float::INFINITY)  # => false
+      #
+      # @example Checking for infinity
+      #   constraint = FinitenessConstraint.new(:self).expecting(:infinite)
+      #   constraint.satisfied?(Float::INFINITY)  # => true
+      #   constraint.satisfied?(42)      # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class FinitenessConstraint
+        # @rbs!
+        #   type expected = :finite | :finite? | :infinite | :infinite?
+
+        include Behavior #[expected, Numeric, {}]
+
+        # Get a human-readable description of the finiteness requirement.
+        #
+        # @return [String] Description of the finiteness requirement
+        # @rbs override
+        def short_description
+          @expected.to_s.delete_suffix('?')
+        end
+
+        # Get a human-readable description of why finiteness validation failed.
+        #
+        # @return [String] Description of the validation failure
+        # @rbs override
+        def short_violation_description
+          if @expected == :finite?
+            'infinite'
+          elsif @expected == :infinite?
+            'finite'
+          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.
+        #
+        # @param expectation [Symbol, String] The finiteness 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 finiteness constraint.
+        #
+        # @return [Boolean] true if the value matches the finiteness requirement
+        # @rbs override
+        def satisfies_constraint?
+          interpret_result(@actual.public_send(@expected))
+        end
+
+        # Validate that the expectation is a valid finiteness check.
+        #
+        # @param expectation [Object] The value to validate
+        #
+        # @raise [ArgumentError] if the expectation is not :finite, :finite?, :infinite, or :infinite?
+        # @return [void]
+        # @rbs override
+        def validate_expectation!(expectation)
+          return if %i[finite? infinite?].include?(expectation)
+
+          raise ArgumentError, "Invalid expectation: #{expectation}. Must be one of :finite, :finite?, :infinite, " \
+                               'or :infinite?'
+        end
+
+        private
+
+        # Interpret the result from Ruby's finite?/infinite? methods.
+        #
+        # Handles the different return values from Ruby's finiteness checking methods:
+        # - finite? returns true/false
+        # - infinite? returns nil (for finite numbers), 1 (for +∞), or -1 (for -∞)
+        #
+        # @example
+        #   interpret_result(true)   # => true
+        #   interpret_result(false)  # => false
+        #   interpret_result(nil)    # => false
+        #   interpret_result(1)      # => true
+        #   interpret_result(-1)     # => true
+        #
+        # @param result [Boolean, Integer, nil] The result from finite? or infinite?
+        #
+        # @return [Boolean] true if the result indicates the desired finiteness 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