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

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

@@ -0,0 +1,258 @@
+module Domainic
+  module Type
+    module Constraint
+      # A module providing core functionality for implementing type constraints.
+      #
+      # The Behavior module serves as the foundation for all type constraints in the Domainic::Type system.
+      # It provides a flexible interface for defining how values should be constrained, supporting both
+      # simple type checking and complex validation rules.
+      #
+      # Key features include:
+      # - Flexible value access through configurable accessors
+      # - Support for custom validation logic
+      # - Coercion hooks for both actual and expected values
+      # - Detailed failure reporting
+      # - Type-aware error messages
+      #
+      # @abstract Implementing classes must override {#satisfies_constraint?} to define their specific
+      #   constraint logic.
+      #
+      # @example Implementing a basic numeric constraint
+      #   class GreaterThanConstraint
+      #     include Domainic::Type::Constraint::Behavior
+      #
+      #     def short_description
+      #       "greater than #{@expected}"
+      #     end
+      #
+      #     def short_violation_description
+      #       @actual.to_s
+      #     end
+      #
+      #     protected
+      #
+      #     def satisfies_constraint?
+      #       @actual > @expected
+      #     end
+      #
+      #     def validate_expectation!(expectation)
+      #       raise ArgumentError, 'Expected value must be numeric' unless expectation.is_a?(Numeric)
+      #     end
+      #   end
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module Behavior[Expected < Object, Actual < Object, Options < Hash[Symbol, untyped]]
+        type options = { ?abort_on_failure: bool, ?coerce_with: Array[Proc] | Proc }
+
+        @result: bool?
+
+        @quantifier_description: (String | Symbol)?
+
+        @options: options
+
+        @expected: Expected
+
+        @actual: Actual
+
+        @accessor: Type::accessor
+
+        attr_reader quantifier_description: (String | Symbol)?
+
+        # Initialize a new constraint instance.
+        #
+        # @param accessor [Symbol] The accessor to use to retrieve the value being constrained
+        # @param quantifier_description [String, Symbol, nil] The description of how the constraint applies
+        #   to elements, such as "all", "any", or "none" for collection constraints, or a specific type name
+        #   for type constraints. Used to form natural language descriptions like "having elements of String"
+        #   or "containing any of [1, 2, 3]"
+        #
+        # @raise [ArgumentError] if the accessor is not included in {VALID_ACCESSORS}
+        # @return [Behavior] A new instance of the constraint.
+        def initialize: (Type::accessor accessor, ?(String | Symbol)? quantifier_description) -> void
+
+        # Whether to abort further validation on an unsatisfied constraint.
+        #
+        # When this is true it tells the type to stop validating the value against the remaining constraints.
+        # This is particularly useful for fundamental type constraints where subsequent validations would
+        # be meaningless if the basic type check fails.
+        #
+        # @return [Boolean] Whether to abort on failure.
+        def abort_on_failure?: () -> bool
+
+        # Set the expected value to compare against.
+        #
+        # @param expectation [Object] The expected value to compare against.
+        #
+        # @raise [ArgumentError] if the expectation is invalid according to {#validate_expectation!}
+        # @return [self] The constraint instance.
+        def expecting: (untyped expectation) -> self
+
+        # Whether the constraint is a failure.
+        #
+        # @return [Boolean] `true` if the constraint is a failure, `false` otherwise.
+        def failure?: () -> bool
+
+        alias failed? failure?
+
+        # The full description of the constraint.
+        #
+        # @return [String, nil] The full description of the constraint.
+        def full_description: () -> String?
+
+        # The full description of the violations that caused the constraint to be unsatisfied.
+        #
+        # @return [String, nil] The full description of the constraint when it fails.
+        def full_violation_description: () -> String?
+
+        # Whether the constraint is satisfied.
+        #
+        # This method orchestrates the constraint validation process by:
+        # 1. Accessing the value using the configured accessor
+        # 2. Coercing the actual value if needed
+        # 3. Checking if the constraint is satisfied
+        # 4. Handling any errors that occur during validation
+        #
+        # @param value [Object] The value to validate against the constraint.
+        #
+        # @return [Boolean] Whether the constraint is satisfied.
+        def satisfied?: (Actual value) -> bool
+
+        # The short description of the constraint.
+        #
+        # This is used to help compose a error message when the constraint is not satisfied.
+        # Implementing classes should override this to provide meaningful descriptions of their
+        # constraint behavior.
+        #
+        # @return [String] The description of the constraint.
+        def short_description: () -> String
+
+        # The short 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: () -> String
+
+        # Whether the constraint is a success.
+        #
+        # @return [Boolean] `true` if the constraint is a success, `false` otherwise.
+        def successful?: () -> bool
+
+        alias success? successful?
+
+        # Merge additional options into the constraint.
+        #
+        # @param options [Hash{String, Symbol => Object}] Additional options
+        # @option options [Boolean] :abort_on_failure (false) Whether to {#abort_on_failure?}
+        # @option options [Array<Proc>, Proc] :coerce_with Coercers to run on the value before validating the
+        #   constraint.
+        #
+        # @return [self] The constraint instance.
+        def with_options: (?options & Options options) -> self
+
+        # Coerce the value being validated into the expected type.
+        #
+        # This hook allows implementing classes to transform the actual value before validation.
+        # This is particularly useful when the constraint needs to handle multiple input formats
+        # or needs to normalize values before comparison.
+        #
+        # @example Coerce input into an array
+        #   def coerce_actual(actual)
+        #     Array(actual)
+        #   end
+        #
+        # @param actual [Object] The actual value to coerce.
+        #
+        # @return [Object] The coerced value.
+        def coerce_actual: (untyped actual) -> Actual
+
+        # Coerce actual values using type-provided coercion procs
+        #
+        # This method processes the actual value through any type-level coercion procs
+        # that were provided via options. This runs after the constraint's own coercion
+        # but before validation.
+        #
+        # @param actual [Object] The actual value to coerce
+        #
+        # @return [Object] The coerced value
+        def coerce_actual_for_type: (untyped actual) -> untyped
+
+        # Coerce the expected value into the expected type.
+        #
+        # This hook allows implementing classes to transform or normalize the expected value
+        # when it's set. This is useful for handling different formats of expected values
+        # or combining multiple expectations.
+        #
+        # @example Coerce a range specification
+        #   def coerce_expectation(expectation)
+        #     case expectation
+        #     when Range then { minimum: expectation.begin, maximum: expectation.end }
+        #     when Hash then @expected.merge(expectation)
+        #     else expectation
+        #     end
+        #   end
+        #
+        # @param expectation [Object] The expected value to coerce.
+        #
+        # @return [Object] The coerced value.
+        def coerce_expectation: (untyped expectation) -> Expected
+
+        # The primary implementation of the constraint.
+        #
+        # This is the core method that all constraints must implement to define their specific
+        # validation logic. It is called by {#satisfied?} after the value has been accessed
+        # and coerced.
+        #
+        # The implementing class has access to two instance variables:
+        # - @actual: The actual value being validated (after coercion)
+        # - @expected: The expected value to validate against (after coercion)
+        #
+        # @example Implementing a greater than constraint
+        #   def satisfies_constraint?
+        #     @actual > @expected
+        #   end
+        #
+        # @raise [NotImplementedError] if the including class doesn't implement this method
+        # @return [Boolean] Whether the constraint is satisfied.
+        def satisfies_constraint?: () -> bool
+
+        # Validate the expected value.
+        #
+        # This hook allows implementing classes to validate the expected value when it's set.
+        # Override this method when the constraint requires specific types or formats for
+        # the expected value.
+        #
+        # @example Validate numeric expectation
+        #   def validate_expectation!(expectation)
+        #     return if expectation.is_a?(Numeric)
+        #
+        #     raise ArgumentError, "Expected value must be numeric, got #{expectation.class}"
+        #   end
+        #
+        # @param expectation [Object] The expected value to validate.
+        #
+        # @return [void]
+        def validate_expectation!: (untyped expectation) -> void
+
+        private
+
+        # Generate the full description for the corresponding short description.
+        #
+        # @param description [String] The short description to expand.
+        #
+        # @return [String] The full description.
+        def full_description_for: (String description) -> String?
+
+        # Validate the accessor.
+        #
+        # @param accessor [Symbol] The accessor to validate.
+        #
+        # @raise [ArgumentError] if the accessor is not included in {VALID_ACCESSORS}.
+        # @return [void]
+        def validate_accessor!: (Type::accessor accessor) -> void
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint that ensures all elements in an enumerable satisfy a given constraint.
+      #
+      # The AllConstraint allows applying a constraint to every element within an enumerable value,
+      # making it possible to validate collections where each element must meet certain criteria.
+      #
+      # Key features:
+      # - Validates each element against the expected constraint
+      # - Short-circuits on first failing element
+      # - Provides clear error messages about failing elements
+      # - Handles empty collections appropriately
+      #
+      # @example Validating array of strings
+      #   string_constraint = StringConstraint.new(:self)
+      #   all_strings = AllConstraint.new(:self, string_constraint)
+      #
+      #   all_strings.satisfied?(['a', 'b', 'c']) # => true
+      #   all_strings.satisfied?(['a', 1, 'c'])   # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class AllConstraint
+        include Behavior[Behavior[untyped, untyped, untyped], Enumerable, { }]
+
+        # Get a description of what the constraint expects.
+        #
+        # @return [String] the constraint description
+        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 satisfy the expected constraint.
+        #
+        # @return [Boolean] whether the constraint is satisfied
+        def satisfies_constraint?: ...
+
+        # Validate that the expectation is a valid constraint.
+        #
+        # @param expectation [Object] the expectation to validate
+        #
+        # @raise [ArgumentError] if the expectation is not a valid constraint
+        # @return [void]
+        def validate_expectation!: ...
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+module Domainic
+  module Type
+    module Constraint
+      # A constraint that combines multiple constraints with logical AND behavior.
+      #
+      # The AndConstraint validates that a value satisfies all of its provided constraints,
+      # implementing logical AND behavior. This enables validation rules like "must be both
+      # a string and non-empty" or "must be numeric and positive".
+      #
+      # Key features:
+      # - Combines multiple constraints with AND logic
+      # - Short-circuits on first failing constraint
+      # - Provides clear error messages for failing validations
+      # - Supports incremental constraint addition
+      #
+      # @example Validating a value is both a String and non-empty
+      #   string_constraint = StringConstraint.new(:self)
+      #   non_empty = LengthConstraint.new(:length, minimum: 1)
+      #   string_and_non_empty = AndConstraint.new(:self, [string_constraint, non_empty])
+      #
+      #   string_and_non_empty.satisfied?("test")  # => true
+      #   string_and_non_empty.satisfied?("")      # => false
+      #   string_and_non_empty.satisfied?(123)     # => false
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      class AndConstraint
+        include Behavior[Array[Behavior[untyped, untyped, untyped]], untyped, { }]
+
+        # Get a description of what the constraint expects.
+        #
+        # @return [String] a description combining all constraint descriptions with 'and'
+        def short_description: ...
+
+        def expecting: (Behavior[untyped, untyped, untyped]) -> self
+
+        # The description of the violations that caused the constraint to be unsatisfied.
+        #
+        # This method provides detailed feedback about which constraints failed,
+        # listing all violations that prevented validation from succeeding.
+        #
+        # @return [String] The combined violation descriptions from all constraints
+        def short_violation_description: ...
+
+        # Coerce the expectation into an array and append new constraints.
+        #
+        # This enables both initializing with an array of constraints and adding
+        # new constraints incrementally via expecting().
+        #
+        # @param expectation [Behavior] the constraint to add
+        #
+        # @return [Array<Behavior>] the updated array of constraints
+        def coerce_expectation: (untyped expectation) -> Array[Behavior[untyped, untyped, untyped]]
+
+        # Check if the value satisfies all expected constraints.
+        #
+        # Short-circuits on the first failing constraint for efficiency.
+        #
+        # @return [Boolean] whether all constraints are satisfied
+        def satisfies_constraint?: ...
+
+        # 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]
+        def validate_expectation!: ...
+      end
+    end
+  end
+end

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

@@ -0,0 +1,57 @@
+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
+        def short_description: ...
+
+        # 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
+        def short_violation_description: ...
+
+        # Check if the value satisfies any of the expected constraints.
+        #
+        # @return [Boolean] whether any constraint is satisfied
+        def satisfies_constraint?: ...
+
+        # 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]
+        def validate_expectation!: ...
+      end
+    end
+  end
+end

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

@@ -0,0 +1,73 @@
+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
+        type expected = :upper | :lower | :mixed | :title
+
+        include Behavior[expected, untyped, { }]
+
+        # Valid case format options
+        #
+        # @return [Array<Symbol>] List of valid case formats
+        VALID_CASES: 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
+        def short_description: ...
+
+        # 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
+        def short_violation_description: ...
+
+        # Check if the string matches the expected case format.
+        #
+        # @return [Boolean] true if the string matches the expected case
+        def satisfies_constraint?: ...
+
+        # 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]
+        def validate_expectation!: ...
+      end
+    end
+  end
+end

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

@@ -0,0 +1,82 @@
+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
+        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: 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
+        def short_description: ...
+
+        # 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
+        def short_violation_description: ...
+
+        # Convert character set name to symbol.
+        #
+        # @param expectation [String, Symbol] The character set name
+        #
+        # @return [Symbol] The character set name as a symbol
+        def coerce_expectation: ...
+
+        # Check if the string contains only characters from the expected set.
+        #
+        # @return [Boolean] true if all characters match the expected set
+        def satisfies_constraint?: ...
+
+        # 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]
+        def validate_expectation!: ...
+      end
+    end
+  end
+end

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

@@ -0,0 +1,91 @@
+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
+        type options = { ?tolerance: Numeric }
+
+        include Behavior[Numeric, Numeric, options]
+
+        # Default tolerance for floating-point arithmetic comparisons.
+        #
+        # @return [Float] The default tolerance value
+        DEFAULT_TOLERANCE: 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
+        def short_description: ...
+
+        # 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
+        def short_violation_description: ...
+
+        # 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
+        def satisfies_constraint?: ...
+
+        # 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]
+        def validate_expectation!: ...
+
+        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
+        def parse_value: (Numeric value) -> Float?
+      end
+    end
+  end
+end