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

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

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+module Domainic
+  module Type
+    module Behavior
+      # A module providing numeric-specific validation behaviors for types.
+      #
+      # This module extends the base Type::Behavior with methods specifically designed for validating numeric values.
+      # It provides a fluent interface for common numeric validations such as divisibility, equality, parity, polarity,
+      # and range constraints. These methods support a variety of constraints and chaining for flexibility in validation
+      # logic.
+      #
+      # @example Basic usage
+      #   class NumericType
+      #     include Domainic::Type::Behavior::NumericBehavior
+      #
+      #     def initialize
+      #       super
+      #       being_positive                  # validates that the value is positive
+      #       being_divisible_by(5)          # validates that the value is divisible by 5
+      #     end
+      #   end
+      #
+      # @example Combining constraints
+      #   class AdvancedNumericType
+      #     include Domainic::Type::Behavior::NumericBehavior
+      #
+      #     def initialize
+      #       super
+      #       being_finite
+      #       being_greater_than_or_equal_to(0)
+      #       being_less_than(100)
+      #     end
+      #   end
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module NumericBehavior
+        # Constrain the numeric value to be divisible by a given divisor.
+        #
+        # @example
+        #   type.being_divisible_by(3)
+        #   type.validate(9)  # => true
+        #   type.validate(10) # => false
+        #
+        # @note the divisor MUST be provided as an argument or in the options Hash.
+        #
+        # @param arguments [Array<Numeric>] a list of arguments, typically one divisor
+        # @param options [Hash] additional options such as tolerance for floating-point checks
+        # @option options [Numeric] :divisor the divisor to check for divisibility
+        # @option options [Numeric] :tolerance the tolerance for floating-point checks
+        #
+        # @return [self] the current instance for chaining
+        # @rbs (*Numeric arguments, ?divisor: Numeric, ?tolerance: Numeric) -> Behavior
+        def being_divisible_by(*arguments, **options)
+          if arguments.size > 1 || (arguments.empty? && !options.key?(:divisor))
+            raise ArgumentError, "wrong number of arguments (given #{arguments.size}, expected 1)"
+          end
+
+          # @type self: Object & Behavior
+          divisor = arguments.first || options[:divisor]
+          constrain :self, :divisibility, divisor, description: 'being', **options.except(:divisor)
+        end
+        alias being_multiple_of being_divisible_by
+        alias divisible_by being_divisible_by
+        alias multiple_of being_divisible_by
+
+        # Constrain the numeric value to equal a specific number.
+        #
+        # @example
+        #   type.being_equal_to(42)
+        #   type.validate(42) # => true
+        #   type.validate(7)  # => false
+        #
+        # @param numeric [Numeric] the number to constrain equality to
+        #
+        # @return [self] the current instance for chaining
+        # @rbs (Numeric numeric) -> Behavior
+        def being_equal_to(numeric)
+          # @type self: Object & Behavior
+          constrain :self, :equality, numeric, description: 'being'
+        end
+        alias eql being_equal_to
+        alias equal_to being_equal_to
+        alias equaling being_equal_to
+
+        # Constrain the numeric value to be even.
+        #
+        # @example
+        #   type.being_even
+        #   type.validate(4) # => true
+        #   type.validate(3) # => false
+        #
+        # @return [self] the current instance for chaining
+        # @rbs () -> Behavior
+        def being_even
+          # @type self: Object & Behavior
+          constrain :self, :parity, :even, description: 'being'
+        end
+        alias even being_even
+        alias not_being_odd being_even
+
+        # Constrain the numeric value to be finite.
+        #
+        # @example
+        #   type.being_finite
+        #   type.validate(42)              # => true
+        #   type.validate(Float::INFINITY) # => false
+        #
+        # @return [self] the current instance for chaining
+        # @rbs () -> Behavior
+        def being_finite
+          # @type self: Object & Behavior
+          constrain :self, :finiteness, :finite, description: 'being'
+        end
+        alias finite being_finite
+        alias not_being_infinite being_finite
+
+        # Constrain the numeric value to be greater than a specific number.
+        #
+        # @example
+        #   type.being_greater_than(5)
+        #   type.validate(10) # => true
+        #   type.validate(3)  # => false
+        #
+        # @param numeric [Numeric] the minimum value (exclusive)
+        #
+        # @return [self] the current instance for chaining
+        # @rbs (Numeric numeric) -> Behavior
+        def being_greater_than(numeric)
+          # @type self: Object & Behavior
+          constrain :self, :range, { minimum: numeric }, inclusive: false, description: 'being'
+        end
+        alias gt being_greater_than
+        alias greater_than being_greater_than
+
+        # Constrain the numeric value to be greater than or equal to a specific number.
+        #
+        # @example
+        #   type.being_greater_than_or_equal_to(5)
+        #   type.validate(5)  # => true
+        #   type.validate(3)  # => false
+        #
+        # @param numeric [Numeric] the minimum value (inclusive)
+        #
+        # @return [self] the current instance for chaining
+        # @rbs (Numeric numeric) -> Behavior
+        def being_greater_than_or_equal_to(numeric)
+          # @type self: Object & Behavior
+          constrain :self, :range, { minimum: numeric }, description: 'being'
+        end
+        alias gte being_greater_than_or_equal_to
+        alias gteq being_greater_than_or_equal_to
+        alias greater_than_or_equal_to being_greater_than_or_equal_to
+
+        # Constrain the numeric value to be infinite.
+        #
+        # @example
+        #   type.being_infinite
+        #   type.validate(Float::INFINITY) # => true
+        #   type.validate(42)             # => false
+        #
+        # @return [self] the current instance for chaining
+        # @rbs () -> Behavior
+        def being_infinite
+          # @type self: Object & Behavior
+          constrain :self, :finiteness, :infinite, description: 'being'
+        end
+        alias infinite being_infinite
+        alias not_being_finite being_infinite
+
+        # Constrain the numeric value to be less than a specific number.
+        #
+        # @example
+        #   type.being_less_than(10)
+        #   type.validate(5)  # => true
+        #   type.validate(10) # => false
+        #
+        # @param numeric [Numeric] the maximum value (exclusive)
+        #
+        # @return [self] the current instance for chaining
+        # @rbs (Numeric numeric) -> Behavior
+        def being_less_than(numeric)
+          # @type self: Object & Behavior
+          constrain :self, :range, { maximum: numeric }, inclusive: false, description: 'being'
+        end
+        alias lt being_less_than
+        alias less_than being_less_than
+
+        # Constrain the numeric value to be less than or equal to a specific number.
+        #
+        # @example
+        #   type.being_less_than_or_equal_to(10)
+        #   type.validate(5)  # => true
+        #   type.validate(15) # => false
+        #
+        # @param numeric [Numeric] the maximum value (inclusive)
+        #
+        # @return [self] the current instance for chaining
+        # @rbs (Numeric numeric) -> Behavior
+        def being_less_than_or_equal_to(numeric)
+          # @type self: Object & Behavior
+          constrain :self, :range, { maximum: numeric }, description: 'being'
+        end
+        alias lte being_less_than_or_equal_to
+        alias lteq being_less_than_or_equal_to
+        alias less_than_or_equal_to being_less_than_or_equal_to
+
+        # Constrain the numeric value to be negative.
+        #
+        # @example
+        #   type.being_negative
+        #   type.validate(-5) # => true
+        #   type.validate(5)  # => false
+        #
+        # @return [self] the current instance for chaining
+        # @rbs () -> Behavior
+        def being_negative
+          # @type self: Object & Behavior
+          constrain :self, :polarity, :negative, description: 'being'
+        end
+        alias negative being_negative
+        alias not_being_positive being_negative
+
+        # Constrain the numeric value to be odd.
+        #
+        # @example
+        #   type.being_odd
+        #   type.validate(3) # => true
+        #   type.validate(4) # => false
+        #
+        # @return [self] the current instance for chaining
+        # @rbs () -> Behavior
+        def being_odd
+          # @type self: Object & Behavior
+          constrain :self, :parity, :odd, description: 'being'
+        end
+        alias odd being_odd
+        alias not_being_even being_odd
+
+        # Constrain the numeric value to be positive.
+        #
+        # @example
+        #   type.being_positive
+        #   type.validate(5)  # => true
+        #   type.validate(-5) # => false
+        #
+        # @return [self] the current instance for chaining
+        # @rbs () -> Behavior
+        def being_positive
+          # @type self: Object & Behavior
+          constrain :self, :polarity, :positive, description: 'being'
+        end
+        alias positive being_positive
+        alias not_being_negative being_positive
+
+        # Constrain the numeric value to be zero.
+        #
+        # @example
+        #   type.being_zero
+        #   type.validate(0) # => true
+        #   type.validate(5) # => false
+        #
+        # @return [self] the current instance for chaining
+        # @rbs () -> Behavior
+        def being_zero
+          # @type self: Object & Behavior
+          constrain :self, :polarity, :zero, description: 'being'
+        end
+        alias zero being_zero
+
+        # Constrain the numeric value to not be divisible by a specific divisor.
+        #
+        # @example
+        #   type.not_being_divisible_by(3)
+        #   type.validate(5)  # => true
+        #   type.validate(9)  # => false
+        #
+        # @note the divisor MUST be provided as an argument or in the options Hash.
+        #
+        # @param arguments [Array<Numeric>] a list of arguments, typically one divisor
+        # @param options [Hash] additional options such as tolerance for floating-point checks
+        # @option options [Numeric] :divisor the divisor to check for divisibility
+        # @option options [Numeric] :tolerance the tolerance for floating-point checks
+        #
+        # @return [self] the current instance for chaining
+        # @rbs (*Numeric arguments, ?divisor: Numeric, ?tolerance: Numeric) -> Behavior
+        def not_being_divisible_by(*arguments, **options)
+          if arguments.size > 1 || (arguments.empty? && !options.key?(:divisor))
+            raise ArgumentError, "wrong number of arguments (given #{arguments.size}, expected 1)"
+          end
+
+          # @type self: Object & Behavior
+          divisor = arguments.first || options[:divisor]
+          divisible_by = @constraints.prepare :self, :divisibility, divisor, **options.except(:divisor)
+          constrain :self, :not, divisible_by, concerning: :divisibility, description: 'being'
+        end
+        alias not_being_multiple_of not_being_divisible_by
+        alias not_divisible_by not_being_divisible_by
+        alias not_multiple_of not_being_divisible_by
+
+        # Constrain the numeric value to not equal a specific number.
+        #
+        # @example
+        #   type.not_being_equal_to(42)
+        #   type.validate(7)  # => true
+        #   type.validate(42) # => false
+        #
+        # @param numeric [Numeric] the number to constrain inequality to
+        #
+        # @return [self] the current instance for chaining
+        # @rbs (Numeric numeric) -> Behavior
+        def not_being_equal_to(numeric)
+          # @type self: Object & Behavior
+          equal_to = @constraints.prepare :self, :equality, numeric
+          constrain :self, :not, equal_to, concerning: :inequality, description: 'being'
+        end
+        alias not_eql not_being_equal_to
+        alias not_equal_to not_being_equal_to
+        alias not_equaling not_being_equal_to
+
+        # Constrain the numeric value to not be zero.
+        #
+        # @example
+        #   type.not_being_zero
+        #   type.validate(5)  # => true
+        #   type.validate(0)  # => false
+        #
+        # @return [self] the current instance for chaining
+        # @rbs () -> Behavior
+        def not_being_zero
+          # @type self: Object & Behavior
+          constrain :self, :polarity, :nonzero, description: 'being'
+        end
+        alias nonzero not_being_zero
+        alias not_zero not_being_zero
+      end
+    end
+  end
+end

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

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'domainic/type/behavior'
+
+module Domainic
+  module Type
+    module Behavior
+      # A module providing size-based validation behaviors for types.
+      #
+      # This module extends the base Type::Behavior with methods specifically designed for validating
+      # the size or length of objects. It provides a consistent interface for size-based validations
+      # across different types (collections, strings, etc) with support for exact, minimum, maximum,
+      # and range-based size constraints.
+      #
+      # Key features:
+      # - Exact size validation
+      # - Minimum/maximum bounds
+      # - Range-based size constraints
+      # - Consistent interface across different types
+      # - Multiple method aliases for intuitive use
+      #
+      # @example Basic usage
+      #   class MyType
+      #     include Domainic::Type::Behavior::SizableBehavior
+      #
+      #     def initialize
+      #       super
+      #       having_size(5)           # exactly 5 elements
+      #       having_minimum_size(3)   # at least 3 elements
+      #       having_maximum_size(10)  # at most 10 elements
+      #     end
+      #   end
+      #
+      # @example Using size ranges
+      #   class MyType
+      #     include Domainic::Type::Behavior::SizableBehavior
+      #
+      #     def initialize
+      #       super
+      #       having_size_between(5, 10)  # between 5 and 10 elements
+      #       # Or with keywords
+      #       having_size_between(minimum: 5, maximum: 10)
+      #     end
+      #   end
+      #
+      # @example Method aliases
+      #   type.having_size(5)          # exact size
+      #   type.size(5)                 # same as above
+      #   type.length(5)               # same as above
+      #   type.count(5)                # same as above
+      #
+      #   type.having_min_size(3)      # minimum size
+      #   type.minimum_size(3)         # same as above
+      #   type.min_length(3)           # same as above
+      #
+      #   type.having_max_size(10)     # maximum size
+      #   type.maximum_size(10)        # same as above
+      #   type.max_length(10)          # same as above
+      #
+      # @author {https://aaronmallen.me Aaron Allen}
+      # @since 0.1.0
+      module SizableBehavior
+        class << self
+          private
+
+          # Parse arguments for having_size_between
+          #
+          # @note this in my opinion is better than polluting the namespace of the including class even with a private
+          #   method. This way, the method is only available within the module itself. See {#having_size_between}.
+          #
+          # @param minimum [Integer, nil] minimum size value from positional args
+          # @param maximum [Integer, nil] maximum size value from positional args
+          # @param options [Hash] keyword arguments containing min/max values
+          #
+          # @raise [ArgumentError] if minimum or maximum value can't be determined
+          # @return [Array<Integer>] parsed [minimum, maximum] values
+          # @rbs (Integer? minimum, Integer? maximum, Hash[Symbol, Integer?] options) -> Array[Integer]
+          def parse_having_between_arguments(minimum, maximum, options)
+            min = minimum || options[:min] || options[:minimum]
+            max = maximum || options[:max] || options[:maximum]
+            raise_having_between_argument_error!(caller, min, max, options) if min.nil? || max.nil?
+
+            [min, max] #: Array[Integer]
+          end
+
+          # Raise appropriate ArgumentError for having_size_between
+          #
+          # @param original_caller [Array<String>] caller stack for error
+          # @param minimum [Integer, nil] attempted minimum value
+          # @param maximum [Integer, nil] attempted maximum value
+          # @param options [Hash] keyword arguments that were provided
+          #
+          # @raise [ArgumentError] with appropriate message
+          # @return [void]
+          # @rbs (
+          #   Array[String] original_caller,
+          #   Integer? minimum,
+          #   Integer? maximum,
+          #   Hash[Symbol, Integer?] options
+          #   ) -> void
+          def raise_having_between_argument_error!(original_caller, minimum, maximum, options)
+            message = if options.empty?
+                        "wrong number of arguments (given #{[minimum, maximum].compact.count}, expected 2)"
+                      else
+                        "missing keyword: :#{%i[minimum maximum].find { |key| !options.key?(key) }}"
+                      end
+
+            error = ArgumentError.new(message)
+            error.set_backtrace(original_caller)
+            raise error
+          end
+        end
+
+        # Set a maximum size constraint
+        #
+        # Creates a constraint ensuring the size of the validated object does not exceed
+        # the specified value.
+        #
+        # @example
+        #   type.having_maximum_size(10)   # size must be <= 10
+        #   type.max_size(10)              # same as above
+        #   type.maximum_count(10)         # same as above
+        #
+        # @param size [Integer] the maximum allowed size
+        # @return [self] for method chaining
+        # @rbs (Integer size) -> Behavior
+        def having_maximum_size(size)
+          # @type self: Object & Behavior
+          constrain :size, :range, { maximum: size },
+                    concerning: :size, description: "having #{__callee__.to_s.split('_').last}"
+        end
+        alias having_max_count having_maximum_size
+        alias having_max_length having_maximum_size
+        alias having_max_size having_maximum_size
+        alias having_maximum_count having_maximum_size
+        alias having_maximum_length having_maximum_size
+        alias max_count having_maximum_size
+        alias max_length having_maximum_size
+        alias max_size having_maximum_size
+        alias maximum_count having_maximum_size
+        alias maximum_length having_maximum_size
+        alias maximum_size having_maximum_size
+
+        # Set a minimum size constraint
+        #
+        # Creates a constraint ensuring the size of the validated object is at least
+        # the specified value.
+        #
+        # @example
+        #   type.having_minimum_size(5)   # size must be >= 5
+        #   type.min_size(5)              # same as above
+        #   type.minimum_count(5)         # same as above
+        #
+        # @param size [Integer] the minimum required size
+        # @return [self] for method chaining
+        # @rbs (Integer size) -> Behavior
+        def having_minimum_size(size)
+          # @type self: Object & Behavior
+          constrain :size, :range, { minimum: size },
+                    concerning: :size, description: "having #{__callee__.to_s.split('_').last}"
+        end
+        alias having_min_count having_minimum_size
+        alias having_min_length having_minimum_size
+        alias having_min_size having_minimum_size
+        alias having_minimum_count having_minimum_size
+        alias having_minimum_length having_minimum_size
+        alias min_count having_minimum_size
+        alias min_length having_minimum_size
+        alias min_size having_minimum_size
+        alias minimum_count having_minimum_size
+        alias minimum_length having_minimum_size
+        alias minimum_size having_minimum_size
+
+        # Set an exact size constraint
+        #
+        # Creates a constraint ensuring the size of the validated object equals
+        # the specified value.
+        #
+        # @example
+        #   type.having_size(7)   # size must be exactly 7
+        #   type.size(7)          # same as above
+        #   type.count(7)         # same as above
+        #
+        # @param size [Integer] the required size
+        # @return [self] for method chaining
+        # @rbs (Integer size) -> Behavior
+        def having_size(size)
+          # @type self: Object & Behavior
+          constrain :size, :range, { minimum: size, maximum: size },
+                    concerning: :size, description: "having #{__callee__.to_s.split('_').last}"
+        end
+        alias count having_size
+        alias having_count having_size
+        alias having_length having_size
+        alias length having_size
+        alias size having_size
+
+        # Set a size range constraint
+        #
+        # Creates a constraint ensuring the size of the validated object falls within
+        # the specified range. The range is exclusive of the minimum and maximum values.
+        #
+        # @example With positional arguments
+        #   type.having_size_between(5, 10)  # 5 < size < 10
+        #
+        # @example With keyword arguments
+        #   type.having_size_between(minimum: 5, maximum: 10)
+        #   type.having_size_between(min: 5, max: 10)
+        #
+        # @example With mixed arguments
+        #   type.having_size_between(5, max: 10)
+        #
+        # @param minimum [Integer, nil] minimum size value (exclusive)
+        # @param maximum [Integer, nil] maximum size value (exclusive)
+        # @param options [Hash] alternate way to specify min/max
+        # @option options [Integer] :min minimum size (exclusive)
+        # @option options [Integer] :minimum same as :min
+        # @option options [Integer] :max maximum size (exclusive)
+        # @option options [Integer] :maximum same as :max
+        #
+        # @raise [ArgumentError] if minimum or maximum value can't be determined
+        # @return [self] for method chaining
+        # @rbs (
+        #   ?Integer? minimum,
+        #   ?Integer? maximum,
+        #   ?max: Integer?,
+        #   ?maximum: Integer?,
+        #   ?min: Integer?,
+        #   ?minimum: Integer?
+        #   ) -> Behavior
+        def having_size_between(minimum = nil, maximum = nil, **options)
+          # @type self: Object & Behavior
+          min, max =
+            SizableBehavior.send(:parse_having_between_arguments, minimum, maximum, options.transform_keys(&:to_sym))
+          constrain :size, :range, { minimum: min, maximum: max },
+                    concerning: :size, description: "having #{__callee__.to_s.split('_').[](1)}", inclusive: false
+        end
+        alias count_between having_size_between
+        alias having_count_between having_size_between
+        alias having_length_between having_size_between
+        alias length_between having_size_between
+        alias size_between having_size_between
+      end
+    end
+  end
+end