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

data/lib/domainic/type/config/registry.yml

@@ -0,0 +1,101 @@
+constraints:
+  all:
+    constant: Domainic::Type::Constraint::AllConstraint
+    require_path: domainic/type/constraint/constraints/all_constraint
+  and:
+    constant: Domainic::Type::Constraint::AndConstraint
+    require_path: domainic/type/constraint/constraints/and_constraint
+  any:
+    constant: Domainic::Type::Constraint::AnyConstraint
+    require_path: domainic/type/constraint/constraints/any_constraint
+  case:
+    constant: Domainic::Type::Constraint::CaseConstraint
+    require_path: domainic/type/constraint/constraints/case_constraint
+  character_set:
+    constant: Domainic::Type::Constraint::CharacterSetConstraint
+    require_path: domainic/type/constraint/constraints/character_set_constraint
+  divisibility:
+    constant: Domainic::Type::Constraint::DivisibilityConstraint
+    require_path: domainic/type/constraint/constraints/divisibility_constraint
+  emptiness:
+    constant: Domainic::Type::Constraint::EmptinessConstraint
+    require_path: domainic/type/constraint/constraints/emptiness_constraint
+  equality:
+    constant: Domainic::Type::Constraint::EqualityConstraint
+    require_path: domainic/type/constraint/constraints/equality_constraint
+  finiteness:
+    constant: Domainic::Type::Constraint::FinitenessConstraint
+    require_path: domainic/type/constraint/constraints/finiteness_constraint
+  inclusion:
+    constant: Domainic::Type::Constraint::InclusionConstraint
+    require_path: domainic/type/constraint/constraints/inclusion_constraint
+  match_pattern:
+    constant: Domainic::Type::Constraint::MatchPatternConstraint
+    require_path: domainic/type/constraint/constraints/match_pattern_constraint
+  method_presence:
+    constant: Domainic::Type::Constraint::MethodPresenceConstraint
+    require_path: domainic/type/constraint/constraints/method_presence_constraint
+  none:
+    constant: Domainic::Type::Constraint::NoneConstraint
+    require_path: domainic/type/constraint/constraints/none_constraint
+  nor:
+    constant: Domainic::Type::Constraint::NorConstraint
+    require_path: domainic/type/constraint/constraints/nor_constraint
+  not:
+    constant: Domainic::Type::Constraint::NotConstraint
+    require_path: domainic/type/constraint/constraints/not_constraint
+  or:
+    constant: Domainic::Type::Constraint::OrConstraint
+    require_path: domainic/type/constraint/constraints/or_constraint
+  ordering:
+    constant: Domainic::Type::Constraint::OrderingConstraint
+    require_path: domainic/type/constraint/constraints/ordering_constraint
+  parity:
+    constant: Domainic::Type::Constraint::ParityConstraint
+    require_path: domainic/type/constraint/constraints/parity_constraint
+  polarity:
+    constant: Domainic::Type::Constraint::PolarityConstraint
+    require_path: domainic/type/constraint/constraints/polarity_constraint
+  range:
+    constant: Domainic::Type::Constraint::RangeConstraint
+    require_path: domainic/type/constraint/constraints/range_constraint
+  type:
+    constant: Domainic::Type::Constraint::TypeConstraint
+    require_path: domainic/type/constraint/constraints/type_constraint
+  uniqueness:
+    constant: Domainic::Type::Constraint::UniquenessConstraint
+    require_path: domainic/type/constraint/constraints/uniqueness_constraint
+types:
+  array:
+    constant: Domainic::Type::ArrayType
+    require_path: domainic/type/types/core/array_type
+  anything:
+    constant: Domainic::Type::AnythingType
+    require_path: domainic/type/types/specification/anything_type
+  duck:
+    constant: Domainic::Type::DuckType
+    require_path: domainic/type/types/specification/duck_type
+  enum:
+    constant: Domainic::Type::EnumType
+    require_path: domainic/type/types/specification/enum_type
+  float:
+    constant: Domainic::Type::FloatType
+    require_path: domainic/type/types/core/float_type
+  hash:
+    constant: Domainic::Type::HashType
+    require_path: domainic/type/types/core/hash_type
+  integer:
+    constant: Domainic::Type::IntegerType
+    require_path: domainic/type/types/core/integer_type
+  string:
+    constant: Domainic::Type::StringType
+    require_path: domainic/type/types/core/string_type
+  symbol:
+    constant: Domainic::Type::SymbolType
+    require_path: domainic/type/types/core/symbol_type
+  union:
+    constant: Domainic::Type::UnionType
+    require_path: domainic/type/types/specification/union_type
+  void:
+    constant: Domainic::Type::VoidType
+    require_path: domainic/type/types/specification/void_type

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

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+require 'domainic/type/accessors'
+
+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
+      # @rbs generic Expected < Object -- The type of @expected
+      # @rbs generic Actual < Object -- The type of @actual
+      # @rbs generic Options < Hash[Symbol, untyped] -- The type of @options
+      module Behavior
+        # @rbs!
+        #   type options = { ?abort_on_failure: bool, ?coerce_with: Array[Proc] | Proc }
+
+        # @rbs @accessor: Type::accessor
+        # @rbs @actual: Actual
+        # @rbs @expected: Expected
+        # @rbs @options: options
+        # @rbs @quantifier_description: (String | Symbol)?
+        # @rbs @result: bool?
+
+        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.
+        # @rbs (Type::accessor accessor, ?(String | Symbol)? quantifier_description) -> void
+        def initialize(accessor, quantifier_description = nil)
+          validate_accessor!(accessor)
+
+          @accessor = accessor.to_sym
+          @options = {}
+          @quantifier_description = quantifier_description
+        end
+
+        # 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.
+        # @rbs () -> bool
+        def abort_on_failure?
+          @options.fetch(:abort_on_failure, false)
+        end
+
+        # 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.
+        # @rbs (untyped expectation) -> self
+        def expecting(expectation)
+          expectation = coerce_expectation(expectation)
+          validate_expectation!(expectation)
+
+          # @type var expectation: Expected
+          @expected = expectation
+          self
+        end
+
+        # Whether the constraint is a failure.
+        #
+        # @return [Boolean] `true` if the constraint is a failure, `false` otherwise.
+        # @rbs () -> bool
+        def failure?
+          @result == false
+        end
+        alias failed? failure?
+
+        # The full description of the constraint.
+        #
+        # @return [String, nil] The full description of the constraint.
+        # @rbs () -> String?
+        def full_description
+          full_description_for(short_description)
+        end
+
+        # 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.
+        # @rbs () -> String?
+        def full_violation_description
+          full_description_for(short_violation_description)
+        end
+
+        # 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.
+        # @rbs (Actual value) -> bool
+        def satisfied?(value)
+          @result = nil
+          constrained = @accessor == :self ? value : value.public_send(@accessor)
+          @actual = coerce_actual(coerce_actual_for_type(constrained))
+          @result = satisfies_constraint? #: bool
+        rescue StandardError
+          @result = false #: bool
+        end
+
+        # 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.
+        # @rbs () -> String
+        def short_description
+          @expected.to_s
+        end
+
+        # 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.
+        # @rbs () -> String
+        def short_violation_description
+          @actual.to_s
+        end
+
+        # Whether the constraint is a success.
+        #
+        # @return [Boolean] `true` if the constraint is a success, `false` otherwise.
+        # @rbs () -> bool
+        def successful?
+          @result == true
+        end
+        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.
+        # @rbs (?(options & Options) options) -> self
+        def with_options(options = {})
+          @options.merge!(options.transform_keys(&:to_sym))
+          self
+        end
+
+        protected
+
+        # 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.
+        # @rbs (untyped actual) -> Actual
+        def coerce_actual(actual)
+          actual
+        end
+
+        # 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
+        # @rbs (untyped actual) -> untyped
+        def coerce_actual_for_type(actual)
+          coercers = @options[:coerce_with]
+          return actual if coercers.nil?
+
+          Array(coercers).reduce(actual) do |accumulator, proc|
+            # @type var proc: Proc
+            proc.call(accumulator)
+          end
+        end
+
+        # 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.
+        # @rbs (untyped expectation) -> Expected
+        def coerce_expectation(expectation)
+          expectation
+        end
+
+        # 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.
+        # @rbs () -> bool
+        def satisfies_constraint?
+          raise NotImplementedError
+        end
+
+        # 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]
+        # @rbs (untyped expectation) -> void
+        def validate_expectation!(expectation); end
+
+        private
+
+        # Generate the full description for the corresponding short description.
+        #
+        # @param description [String] The short description to expand.
+        #
+        # @return [String] The full description.
+        # @rbs (String description) -> String?
+        def full_description_for(description)
+          return if quantifier_description.to_s.include?('not_described')
+
+          if quantifier_description.is_a?(Symbol)
+            "#{quantifier_description.to_s.split('_').join(' ')} #{description}"
+          else
+            "#{quantifier_description} #{description}"
+          end.strip
+        end
+
+        # Validate the accessor.
+        #
+        # @param accessor [Symbol] The accessor to validate.
+        #
+        # @raise [ArgumentError] if the accessor is not included in {VALID_ACCESSORS}.
+        # @return [void]
+        # @rbs (Type::accessor accessor) -> void
+        def validate_accessor!(accessor)
+          return if Type::ACCESSORS.include?(accessor)
+
+          raise ArgumentError, "Invalid accessor: #{accessor} must be one of #{Type::ACCESSORS.sort.join(', ')}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+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
+        # @rbs override
+        def short_description
+          @expected.short_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
+          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 all elements satisfy the expected constraint.
+        #
+        # @return [Boolean] whether the constraint is satisfied
+        # @rbs override
+        def satisfies_constraint?
+          @actual.all? { |element| @expected.satisfied?(element) }
+        end
+
+        # 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]
+        # @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/and_constraint.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'domainic/type/constraint/behavior'
+
+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'
+        # @rbs override
+        def short_description
+          descriptions = @expected.map(&:short_description)
+          return descriptions.first if descriptions.size == 1
+          return '' if descriptions.empty?
+
+          *first, last = descriptions
+          "#{first.join(', ')} and #{last}"
+        end
+
+        # @rbs! 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
+        # @rbs override
+        def short_violation_description
+          violations = @expected.reject { |constraint| constraint.satisfied?(@actual) }
+          descriptions = violations.map(&:short_violation_description)
+          return descriptions.first if descriptions.size == 1
+
+          *first, last = descriptions
+          "#{first.join(', ')} nor #{last}"
+        end
+
+        protected
+
+        # 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
+        # @rbs (untyped expectation) -> Array[Behavior[untyped, untyped, untyped]]
+        def coerce_expectation(expectation)
+          expectation.is_a?(Array) ? (@expected || []).concat(expectation) : (@expected || []) << expectation
+        end
+
+        # Check if the value satisfies all expected constraints.
+        #
+        # Short-circuits on the first failing constraint for efficiency.
+        #
+        # @return [Boolean] whether all constraints are satisfied
+        # @rbs override
+        def satisfies_constraint?
+          @expected.all? { |constraint| constraint.satisfied?(@actual) }
+        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?(Array) && expectation.all?(Behavior)
+
+          raise ArgumentError, 'Expectation must be a Domainic::Type::Constraint'
+        end
+      end
+    end
+  end
+end