stannum 0.1.0

data/lib/stannum/constraints/type.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/base'
+require 'stannum/support/optional'
+
+module Stannum::Constraints
+  # A type constraint asserts that the object is of the expected type.
+  #
+  # @example Using a Type constraint with a Class
+  #   constraint = Stannum::Constraints::Type.new(StandardError)
+  #
+  #   constraint.matches?(nil)               # => false
+  #   constraint.matches?(Object.new)        # => false
+  #   constraint.matches?(StandardError.new) # => true
+  #   constraint.matches?(RuntimeError.new)  # => true
+  #
+  # @example Using a Type constraint with a Module
+  #   constraint = Stannum::Constraints::Type.new(Enumerable)
+  #
+  #   constraint.matches?(nil)                           #=> false
+  #   constraint.matches?(Object.new)                    #=> false
+  #   constraint.matches?(Array)                         #=> true
+  #   constraint.matches?(Object.new.extend(Enumerable)) #=> true
+  #
+  # @example Using a Type constraint with a Class name
+  #   constraint = Stannum::Constraints::Type.new('StandardError')
+  #
+  #   constraint.matches?(nil)               # => false
+  #   constraint.matches?(Object.new)        # => false
+  #   constraint.matches?(StandardError.new) # => true
+  #   constraint.matches?(RuntimeError.new)  # => true
+  class Type < Stannum::Constraints::Base
+    include Stannum::Support::Optional
+
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.is_type'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.is_not_type'
+
+    # @param expected_type [Class, Module, String] The type the object is
+    #   expected to belong to. Can be a Class or a Module, or the name of a
+    #   class or module.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(expected_type, optional: nil, required: nil, **options)
+      expected_type = resolve_expected_type(expected_type)
+
+      super(
+        expected_type: expected_type,
+        **resolve_required_option(
+          optional: optional,
+          required: required,
+          **options
+        )
+      )
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
+      (errors || Stannum::Errors.new).add(type, **error_properties)
+    end
+
+    # @return [Class, Module, String] the type the object is expected to belong
+    #   to.
+    def expected_type
+      options[:expected_type]
+    end
+
+    # Checks that the object is an instance of the expected type.
+    #
+    # @return [true, false] true if the object is an instance of the expected
+    #   type, otherwise false.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      matches_type?(actual)
+    end
+    alias match? matches?
+
+    # (see Stannum::Constraints::Base#negated_errors_for)
+    def negated_errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
+      (errors || Stannum::Errors.new).add(negated_type, **error_properties)
+    end
+
+    # (see Stannum::Constraints::Base#with_options)
+    def with_options(**options)
+      options = options.merge(required_by_default: required?)
+
+      super(**resolve_required_option(**options))
+    end
+
+    private
+
+    def error_properties
+      { required: required?, type: expected_type }
+    end
+
+    def matches_type?(actual)
+      actual.is_a?(expected_type) || (optional? && actual.nil?)
+    end
+
+    def resolve_expected_type(type_or_name)
+      return type_or_name if type_or_name.is_a?(Module)
+
+      return Object.const_get(type_or_name) if type_or_name.is_a?(String)
+
+      raise ArgumentError,
+        'expected type must be a Class or Module',
+        caller[1..-1]
+    end
+  end
+end

data/lib/stannum/constraints/types/array_type.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+require 'stannum/support/coercion'
+
+module Stannum::Constraints::Types
+  # An Array type constraint asserts that the object is an Array.
+  #
+  # @example Using an Array type constraint
+  #   constraint = Stannum::Constraints::Types::ArrayType.new
+  #
+  #   constraint.matches?(nil)        # => false
+  #   constraint.matches?(Object.new) # => false
+  #   constraint.matches?([])         # => true
+  #   constraint.matches?([1, 2, 3])  # => true
+  #
+  # @example Using an Array type constraint with an item constraint
+  #   constraint = Stannum::Constraints::Types::ArrayType.new(item_type: String)
+  #
+  #   constraint.matches?(nil)               # => false
+  #   constraint.matches?(Object.new)        # => false
+  #   constraint.matches?([])                # => true
+  #   constraint.matches?([1, 2, 3])         # => false
+  #   constraint.matches?(%w[one two three]) # => true
+  #
+  # @example Using an Array type constraint with a presence constraint
+  #   constraint = Stannum::Constraints::Types::ArrayType.new(allow_empty: false)
+  #
+  #   constraint.matches?(nil)               # => false
+  #   constraint.matches?(Object.new)        # => false
+  #   constraint.matches?([])                # => false
+  #   constraint.matches?([1, 2, 3])         # => true
+  #   constraint.matches?(%w[one two three]) # => true
+  class ArrayType < Stannum::Constraints::Type
+    # @param allow_empty [true, false] If false, then the constraint will not
+    #   match against an Array with no items.
+    # @param item_type [Stannum::Constraints::Base, Class, nil] If set, then
+    #   the constraint will check the types of each item in the Array against
+    #   the expected type and will fail if any items do not match.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(allow_empty: true, item_type: nil, **options)
+      super(
+        ::Array,
+        allow_empty: !!allow_empty,
+        item_type:   coerce_item_type(item_type),
+        **options
+      )
+    end
+
+    # @return [true, false] if false, then the constraint will not
+    #   match against an Array with no items.
+    def allow_empty?
+      options[:allow_empty]
+    end
+
+    # Checks that the object is not an Array instance.
+    #
+    # @return [true, false] true if the object is not an Array instance,
+    #   otherwise false.
+    #
+    # @see Stannum::Constraints::Types::ArrayType#matches?
+    def does_not_match?(actual)
+      !matches_type?(actual)
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      return super unless actual.is_a?(expected_type)
+
+      errors ||= Stannum::Errors.new
+
+      return add_presence_error(errors) unless presence_matches?(actual)
+
+      unless item_type_matches?(actual)
+        non_matching_items(actual).each do |item, index|
+          item_type.errors_for(item, errors: errors[index])
+        end
+      end
+
+      errors
+    end
+
+    # @return [Stannum::Constraints::Base, nil] the expected type for the items
+    #   in the array.
+    def item_type
+      options[:item_type]
+    end
+
+    # Checks that the object is an Array instance and that the items match.
+    #
+    # If the constraint was configured with an item_type, each item in the Array
+    # will be compared to the expected type. If any items do not match the
+    # expectation, then #matches? will return false.
+    #
+    # @return [true, false] true if the object is an Array instance with
+    #   matching items, otherwise false.
+    #
+    # @see Stannum::Constraints::Types::ArrayType#does_not_match?
+    def matches?(actual)
+      return false unless super
+
+      return false unless presence_matches?(actual)
+
+      return false unless item_type_matches?(actual)
+
+      true
+    end
+    alias match? matches?
+
+    private
+
+    def add_presence_error(errors)
+      errors.add(
+        Stannum::Constraints::Presence::TYPE,
+        **error_properties
+      )
+    end
+
+    def coerce_item_type(item_type)
+      Stannum::Support::Coercion.type_constraint(
+        item_type,
+        allow_nil: true,
+        as:        'item type'
+      )
+    end
+
+    def error_properties
+      super().merge(allow_empty: allow_empty?)
+    end
+
+    def item_type_matches?(actual)
+      return true unless item_type
+
+      return true if actual.nil?
+
+      actual.all? { |item| item_type.matches?(item) }
+    end
+
+    def non_matching_items(actual)
+      actual.each.with_index.reject { |item, _| item_type.matches?(item) }
+    end
+
+    def presence_matches?(actual)
+      allow_empty? || !actual.empty?
+    end
+  end
+end

data/lib/stannum/constraints/types/big_decimal_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'bigdecimal'
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # A BigDecimal type constraint asserts that the object is a BigDecimal.
+  class BigDecimalType < Stannum::Constraints::Type
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::BigDecimal, **options)
+    end
+  end
+end

data/lib/stannum/constraints/types/date_time_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'date'
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # A DateTimeType constraint asserts that the object is a DateTime.
+  class DateTimeType < Stannum::Constraints::Type
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::DateTime, **options)
+    end
+  end
+end

data/lib/stannum/constraints/types/date_type.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'date'
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # A DateType constraint asserts that the object is a Date.
+  class DateType < Stannum::Constraints::Type
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::Date, **options)
+    end
+  end
+end

data/lib/stannum/constraints/types/float_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # A FloatType constraint asserts that the object is a Float.
+  class FloatType < Stannum::Constraints::Type
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::Float, **options)
+    end
+  end
+end

data/lib/stannum/constraints/types/hash_type.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+require 'stannum/support/coercion'
+
+module Stannum::Constraints::Types
+  # A Hash type constraint asserts that the object is a Hash.
+  #
+  # @example Using a Hash type constraint
+  #   constraint = Stannum::Constraints::Types::HashType.new
+  #
+  #   constraint.matches?(nil)              # => false
+  #   constraint.matches?(Object.new)       # => false
+  #   constraint.matches?({})               # => true
+  #   constraint.matches?({ key: 'value' }) # => true
+  #
+  # @example Using a Hash type constraint with a key constraint
+  #   constraint = Stannum::Constraints::Types::HashType.new(key_type: String)
+  #
+  #   constraint.matches?(nil)                  # => false
+  #   constraint.matches?(Object.new)           # => false
+  #   constraint.matches?({})                   # => true
+  #   constraint.matches?({ key: 'value' })     # => false
+  #   constraint.matches?({ 'key' => 'value' }) # => true
+  #
+  # @example Using a Hash type constraint with a value constraint
+  #   constraint = Stannum::Constraints::Types::HashType.new(value_type: String)
+  #
+  #   constraint.matches?(nil)              # => false
+  #   constraint.matches?(Object.new)       # => false
+  #   constraint.matches?({})               # => true
+  #   constraint.matches?({ key: :value })  # => false
+  #   constraint.matches?({ key: 'value' }) # => true
+  #
+  # @example Using a Hash type constraint with a presence constraint
+  #   constraint = Stannum::Constraints::Types::HashType.new(allow_empty: false)
+  #
+  #   constraint.matches?(nil)              # => false
+  #   constraint.matches?(Object.new)       # => false
+  #   constraint.matches?({})               # => false
+  #   constraint.matches?({ key: :value })  # => true
+  #   constraint.matches?({ key: 'value' }) # => true
+  class HashType < Stannum::Constraints::Type
+    # @param allow_empty [true, false] If false, then the constraint will not
+    #   match against a Hash with no keys.
+    # @param key_type [Stannum::Constraints::Base, Class, nil] If set, then the
+    #   constraint will check the types of each key in the Hash against the
+    #   expected type and will fail if any keys do not match.
+    # @param value_type [Stannum::Constraints::Base, Class, nil] If set, then
+    #   the constraint will check the types of each value in the Hash against
+    #   the expected type and will fail if any values do not match.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(allow_empty: true, key_type: nil, value_type: nil, **options)
+      super(
+        ::Hash,
+        allow_empty: !!allow_empty,
+        key_type:    coerce_key_type(key_type),
+        value_type:  coerce_value_type(value_type),
+        **options
+      )
+    end
+
+    # @return [true, false] if false, then the constraint will not
+    #   match against a Hash with no keys.
+    def allow_empty?
+      options[:allow_empty]
+    end
+
+    # Checks that the object is not a Hash instance.
+    #
+    # @return [true, false] true if the object is not a Hash instance, otherwise
+    #   false.
+    #
+    # @see Stannum::Constraints::Types::HashType#matches?
+    def does_not_match?(actual)
+      !matches_type?(actual)
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      return super unless actual.is_a?(expected_type)
+
+      errors ||= Stannum::Errors.new
+
+      return add_presence_error(errors) unless presence_matches?(actual)
+
+      update_key_errors_for(actual: actual, errors: errors)
+
+      update_value_errors_for(actual: actual, errors: errors)
+
+      errors
+    end
+
+    # @return [Stannum::Constraints::Base, nil] the expected type for the keys
+    #   in the hash.
+    def key_type
+      options[:key_type]
+    end
+
+    # Checks that the object is a Hash instance and that the keys/values match.
+    #
+    # If the constraint was configured with a key_type, each key in the hash
+    # will be compared to the expected type. Likewise, if the constraint was
+    # configured with a value_type, each value in the hash will be compared. If
+    # any keys and/or values do not match the expectation, then #matches? will
+    # return false.
+    #
+    # @return [true, false] true if the object is a Hash instance with matching
+    #   keys and values, otherwise false.
+    #
+    # @see Stannum::Constraints::Types::HashType#does_not_match?
+    def matches?(actual)
+      return false unless super
+
+      return false unless presence_matches?(actual)
+
+      return false unless key_type_matches?(actual)
+
+      return false unless value_type_matches?(actual)
+
+      true
+    end
+    alias match? matches?
+
+    # @return [Stannum::Constraints::Base, nil] the expected type for the values
+    #   in the hash.
+    def value_type
+      options[:value_type]
+    end
+
+    private
+
+    def add_presence_error(errors)
+      errors.add(
+        Stannum::Constraints::Presence::TYPE,
+        **error_properties
+      )
+    end
+
+    def coerce_key_type(key_type)
+      Stannum::Support::Coercion.type_constraint(
+        key_type,
+        allow_nil: true,
+        as:        'key type'
+      )
+    end
+
+    def coerce_value_type(value_type)
+      Stannum::Support::Coercion.type_constraint(
+        value_type,
+        allow_nil: true,
+        as:        'value type'
+      )
+    end
+
+    def error_properties
+      super().merge(allow_empty: allow_empty?)
+    end
+
+    def key_type_matches?(actual)
+      return true unless key_type
+
+      return true if actual.nil?
+
+      actual.each_key.all? { |key| key_type.matches?(key) }
+    end
+
+    def non_matching_keys(actual)
+      return [] unless key_type && actual.is_a?(Hash)
+
+      actual.each_key.reject { |key| key_type.matches?(key) }
+    end
+
+    def non_matching_values(actual)
+      return [] unless value_type && actual.is_a?(Hash)
+
+      actual.each.reject { |_, value| value_type.matches?(value) }
+    end
+
+    def presence_matches?(actual)
+      allow_empty? || !actual.empty?
+    end
+
+    def update_key_errors_for(actual:, errors:)
+      non_matching_keys(actual).each do |key|
+        key_type.errors_for(key, errors: errors[:keys][key])
+      end
+    end
+
+    def update_value_errors_for(actual:, errors:)
+      non_matching_values(actual).each do |key, value|
+        value_type.errors_for(value, errors: errors[key])
+      end
+    end
+
+    def value_type_matches?(actual)
+      return true unless value_type
+
+      return true if actual.nil?
+
+      actual.each_value.all? { |value| value_type.matches?(value) }
+    end
+  end
+end

data/lib/stannum/constraints/types/hash_with_indifferent_keys.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # Asserts that the object is a Hash with String or Symbol keys.
+  class HashWithIndifferentKeys < Stannum::Constraints::Types::HashType
+    # @param value_type [Stannum::Constraints::Base, Class, nil] If set, then
+    #   the constraint will check the types of each value in the Hash against
+    #   the expected type and will fail if any values do not match.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(value_type: nil, **options)
+      super(
+        key_type:   Stannum::Constraints::Hashes::IndifferentKey.new,
+        value_type: coerce_value_type(value_type),
+        **options
+      )
+    end
+  end
+end

data/lib/stannum/constraints/types/hash_with_string_keys.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # Asserts that the object is a Hash with String keys.
+  class HashWithStringKeys < Stannum::Constraints::Types::HashType
+    # @param value_type [Stannum::Constraints::Base, Class, nil] If set, then
+    #   the constraint will check the types of each value in the Hash against
+    #   the expected type and will fail if any values do not match.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(value_type: nil, **options)
+      super(
+        key_type:   Stannum::Constraints::Types::StringType.new,
+        value_type: coerce_value_type(value_type),
+        **options
+      )
+    end
+  end
+end

data/lib/stannum/constraints/types/hash_with_symbol_keys.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # Asserts that the object is a Hash with Symbol keys.
+  class HashWithSymbolKeys < Stannum::Constraints::Types::HashType
+    # @param value_type [Stannum::Constraints::Base, Class, nil] If set, then
+    #   the constraint will check the types of each value in the Hash against
+    #   the expected type and will fail if any values do not match.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(value_type: nil, **options)
+      super(
+        key_type:   Stannum::Constraints::Types::SymbolType.new,
+        value_type: coerce_value_type(value_type),
+        **options
+      )
+    end
+  end
+end

data/lib/stannum/constraints/types/integer_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # An IntegerType constraint asserts that the object is an Integer.
+  class IntegerType < Stannum::Constraints::Type
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::Integer, **options)
+    end
+  end
+end

data/lib/stannum/constraints/types/nil_type.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # A Nil type constraint asserts that the object is nil.
+  class NilType < Stannum::Constraints::Type
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.types.is_nil'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.types.is_not_nil'
+
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::NilClass, **options)
+    end
+  end
+end

data/lib/stannum/constraints/types/proc_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # A Proc type constraint asserts that the object is a Proc.
+  class ProcType < Stannum::Constraints::Type
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::Proc, **options)
+    end
+  end
+end

data/lib/stannum/constraints/types/string_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # A String type constraint asserts that the object is a String.
+  class StringType < Stannum::Constraints::Type
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::String, **options)
+    end
+  end
+end

data/lib/stannum/constraints/types/symbol_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types'
+
+module Stannum::Constraints::Types
+  # A Symbol type constraint asserts that the object is a Symbol.
+  class SymbolType < Stannum::Constraints::Type
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(**options)
+      super(::Symbol, **options)
+    end
+  end
+end