stannum 0.1.0

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

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

data/lib/stannum/constraints/types.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # Namespace for type constraints.
+  module Types
+    autoload :ArrayType,      'stannum/constraints/types/array_type'
+    autoload :DateType,       'stannum/constraints/types/date_type'
+    autoload :DateTimeType,   'stannum/constraints/types/date_time_type'
+    autoload :BigDecimalType, 'stannum/constraints/types/big_decimal_type'
+    autoload :FloatType,      'stannum/constraints/types/float_type'
+    autoload :HashType,       'stannum/constraints/types/hash_type'
+    autoload :HashWithIndifferentKeys,
+      'stannum/constraints/types/hash_with_indifferent_keys'
+    autoload :HashWithStringKeys,
+      'stannum/constraints/types/hash_with_string_keys'
+    autoload :IntegerType,    'stannum/constraints/types/integer_type'
+    autoload :NilType,        'stannum/constraints/types/nil_type'
+    autoload :ProcType,       'stannum/constraints/types/proc_type'
+    autoload :StringType,     'stannum/constraints/types/string_type'
+    autoload :SymbolType,     'stannum/constraints/types/symbol_type'
+    autoload :TimeType,       'stannum/constraints/types/time_type'
+  end
+end

data/lib/stannum/constraints/union.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/base'
+
+module Stannum::Constraints
+  # Asserts that the object matches one of the given constraints.
+  #
+  # @example Using a Union Constraint.
+  #   false_constraint = Stannum::Constraint.new { |actual| actual == false }
+  #   true_constraint  = Stannum::Constraint.new { |actual| actual == true }
+  #   union_constraint = Stannum::Constraints::Union.new(
+  #     false_constraint,
+  #     true_constraint
+  #   )
+  #
+  #   constraint.matches?(nil)   #=> false
+  #   constraint.matches?(false) #=> true
+  #   constraint.matches?(true)  #=> true
+  class Union < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.is_in_union'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.is_not_in_union'
+
+    # @overload initialize(*expected_constraints, **options)
+    #   @param expected_constraints [Array<Stannum::Constraints::Base>] The
+    #     possible values for the object.
+    #   @param options [Hash<Symbol, Object>] Configuration options for the
+    #     constraint. Defaults to an empty Hash.
+    def initialize(first, *rest, **options)
+      expected_constraints = rest.unshift(first)
+
+      super(expected_constraints: expected_constraints, **options)
+
+      @expected_constraints = expected_constraints
+    end
+
+    # @return [Array<Stannum::Constraints::Base>] the possible values for the
+    #   object.
+    attr_reader :expected_constraints
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
+      (errors || Stannum::Errors.new).add(type, constraints: expected_values)
+    end
+
+    # Checks that the object matches at least one of the given constraints.
+    #
+    # @return [true, false] false if the object matches a constraint, otherwise
+    #   false.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      expected_constraints.any? { |constraint| constraint.matches?(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, constraints: negated_values)
+    end
+
+    private
+
+    def expected_values
+      @expected_constraints.map do |constraint|
+        {
+          options: constraint.options,
+          type:    constraint.type
+        }
+      end
+    end
+
+    def negated_values
+      @expected_constraints.map do |constraint|
+        {
+          negated_type: constraint.negated_type,
+          options:      constraint.options
+        }
+      end
+    end
+  end
+end

data/lib/stannum/constraints.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'stannum'
+
+module Stannum
+  # Namespace for pre-defined constraints.
+  module Constraints
+    autoload :Absence,    'stannum/constraints/absence'
+    autoload :Anything,   'stannum/constraints/anything'
+    autoload :Base,       'stannum/constraints/base'
+    autoload :Boolean,    'stannum/constraints/boolean'
+    autoload :Delegator,  'stannum/constraints/delegator'
+    autoload :Enum,       'stannum/constraints/enum'
+    autoload :Equality,   'stannum/constraints/equality'
+    autoload :Hashes,     'stannum/constraints/hashes'
+    autoload :Identity,   'stannum/constraints/identity'
+    autoload :Nothing,    'stannum/constraints/nothing'
+    autoload :Presence,   'stannum/constraints/presence'
+    autoload :Signature,  'stannum/constraints/signature'
+    autoload :Signatures, 'stannum/constraints/signatures'
+    autoload :Tuples,     'stannum/constraints/tuples'
+    autoload :Type,       'stannum/constraints/type'
+    autoload :Types,      'stannum/constraints/types'
+    autoload :Union,      'stannum/constraints/union'
+  end
+end

data/lib/stannum/contract.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+require 'stannum'
+require 'stannum/contracts/base'
+
+module Stannum
+  # A Contract defines constraints on an object and its properties.
+  #
+  # @example Creating A Contract With Property Constraints
+  #   Widget = Struct.new(:name, :manufacturer)
+  #   Manufacturer = Struct.new(:factory)
+  #   Factory = Struct.new(:address)
+  #
+  #   type_constraint = Stannum::Constraints::Type.new(Widget)
+  #   name_constraint =
+  #     Stannum::Constraint.new(type: 'wrong_name', negated_type: 'right_name') do |value|
+  #       value == 'Self-sealing Stem Bolt'
+  #     end
+  #   address_constraint =
+  #     Stannum::Constraint.new(type: 'wrong_address', negated_type: 'right_address') do |value|
+  #       value == '123 Example Street'
+  #     end
+  #   contract =
+  #     Stannum::Contract.new
+  #     .add_constraint(type_constraint)
+  #     .add_constraint(name_constraint, property: :name)
+  #     .add_constraint(address_constraint, property: %i[manufacturer factory address])
+  #
+  # @example With An Object That Matches None Of The Property Constraints
+  #   # With a non-Widget object.
+  #   contract.matches?(nil) #=> false
+  #   errors = contract.errors_for(nil)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_not_type', data: { type: Widget }, path: [], message: nil },
+  #     { type: 'wrong_name', data: {}, path: [:name], message: nil },
+  #     { type: 'wrong_address', data: {}, path: [:manufacturer, :factory, :address], message: nil }
+  #   ]
+  #   errors[:name].to_a
+  #   #=> [
+  #     { type: 'wrong_name', data: {}, path: [], message: nil }
+  #   ]
+  #   errors[:manufacturer].to_a
+  #   #=> [
+  #     { type: 'wrong_address', data: {}, path: [:factory, :address], message: nil }
+  #   ]
+  #
+  #   contract.does_not_match?(nil)          #=> true
+  #   contract.negated_errors_for?(nil).to_a #=> []
+  #
+  # @example With An Object That Matches Some Of The Property Constraints
+  #   contract.matches?(Widget.new) #=> false
+  #   errors = contract.errors_for(Widget.new)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'wrong_name', data: {}, path: [:name], message: nil },
+  #     { type: 'wrong_address', data: {}, path: [:manufacturer, :factory, :address], message: nil }
+  #   ]
+  #
+  #   contract.does_not_match?(Widget.new) #=> false
+  #   errors = contract.negated_errors_for(Widget.new)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_type', data: { type: Widget }, path: [], message: nil }
+  #   ]
+  #
+  # @example With An Object That Matches All Of The Property Constraints
+  #   factory      = Factory.new('123 Example Street')
+  #   manufacturer = Manufacturer.new(factory)
+  #   widget       = Widget.new('Self-sealing Stem Bolt', manufacturer)
+  #   contract.matches?(widget)        #=> true
+  #   contract.errors_for(widget).to_a #=> []
+  #
+  #   contract.does_not_match?(widget) #=> true
+  #   errors = contract.negated_errors_for(widget)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_type', data: { type: Widget }, path: [], message: nil },
+  #     { type: 'right_name', data: {}, path: [:name], message: nil },
+  #     { type: 'right_address', data: {}, path: [:manufacturer, :factory, :address], message: nil }
+  #   ]
+  #
+  # @example Defining A Custom Contract
+  #   user_contract = Stannum::Contract.new do
+  #     # Sanity constraints are evaluated first, and if a sanity constraint
+  #     # fails, the contract will immediately halt.
+  #     constraint Stannum::Constraints::Type.new(User), sanity: true
+  #
+  #     # You can also define a constraint using a block.
+  #     constraint(type: 'example.is_not_user') do |user|
+  #       user.role == 'user'
+  #     end
+  #
+  #     # You can define a constraint on a property of the object.
+  #     property :name, Stannum::Constraints::Presence.new
+  #   end
+  #
+  # @see Stannum::Contracts::Base.
+  class Contract < Stannum::Contracts::Base
+    # Builder class for defining item constraints for a Contract.
+    #
+    # This class should not be invoked directly. Instead, pass a block to the
+    # constructor for Contract.
+    #
+    # @api private
+    class Builder < Stannum::Contracts::Base::Builder
+      # Defines a property constraint on the contract.
+      #
+      # @overload property(property, constraint, **options)
+      #   Adds the given constraint to the contract for the property.
+      #
+      #   @param property [String, Symbol, Array<String, Symbol>] The property
+      #     to constrain.
+      #   @param constraint [Stannum::Constraint::Base] The constraint to add.
+      #   @param options [Hash<Symbol, Object>] Options for the constraint.
+      #
+      # @overload property(**options) { |value| }
+      #   Creates a new Stannum::Constraint object with the given block, and
+      #   adds that constraint to the contract for the property.
+      def property(property, constraint = nil, **options, &block)
+        self.constraint(
+          constraint,
+          property: property,
+          **options,
+          &block
+        )
+      end
+    end
+
+    # (see Stannum::Contracts::Base#add_constraint)
+    #
+    # If the :property option is set, this defines a property constraint. See
+    # #add_property_constraint for more information.
+    #
+    # @param property [String, Symbol, Array<String, Symbol>, nil] The
+    #   property to match.
+    #
+    # @see #add_property_constraint.
+    def add_constraint(constraint, property: nil, sanity: false, **options)
+      validate_constraint(constraint)
+      validate_property(property: property, **options)
+
+      @constraints << Stannum::Contracts::Definition.new(
+        constraint: constraint,
+        contract:   self,
+        options:    options.merge(property: property, sanity: sanity)
+      )
+
+      self
+    end
+
+    # Adds a property constraint to the contract.
+    #
+    # When the contract is called, the contract will find the value of that
+    # property for the given object. If the property is an array, the contract
+    # will recursively retrieve each property.
+    #
+    # A property of nil will match against the given object itself, rather
+    # than one of its properties.
+    #
+    # If the value does not match the constraint, then the error from the
+    # constraint will be added in an error namespace matching the constraint.
+    # For example, a property of :name will add the error message to
+    # errors.dig(:name), while a property of [:manufacturer, :address, :street]
+    # will add the error message to
+    # errors.dig(:manufacturer, :address, :street).
+    #
+    # @param property [String, Symbol, Array<String, Symbol>, nil] The
+    #   property to match.
+    # @param constraint [Stannum::Constraints::Base] The constraint to add.
+    # @param sanity [true, false] Marks the constraint as a sanity constraint,
+    #   which is always matched first and will always short-circuit on a failed
+    #   match.
+    # @param options [Hash<Symbol, Object>] Options for the constraint. These
+    #   can be used by subclasses to define the value and error mappings for the
+    #   constraint.
+    #
+    # @return [self] the contract.
+    #
+    # @see #add_constraint.
+    def add_property_constraint(property, constraint, sanity: false, **options)
+      add_constraint(constraint, property: property, sanity: sanity, **options)
+    end
+
+    protected
+
+    def map_errors(errors, **options)
+      property_name = options.fetch(:property_name, options[:property])
+
+      return errors if property_name.nil?
+
+      errors.dig(*Array(property_name))
+    end
+
+    def map_value(actual, **options)
+      property = options[:property]
+
+      return actual if property.nil?
+
+      access_nested_property(actual, property)
+    end
+
+    private
+
+    def access_nested_property(object, property)
+      Array(property).reduce(object) { |obj, prop| access_property(obj, prop) }
+    end
+
+    def access_property(object, property)
+      object.send(property) if object.respond_to?(property, true)
+    end
+
+    def valid_property?(property: nil, **_options)
+      if property.is_a?(Array)
+        return false if property.empty?
+
+        return property.all? { |item| valid_property_name?(item) }
+      end
+
+      valid_property_name?(property)
+    end
+
+    def valid_property_name?(name)
+      return false unless name.is_a?(String) || name.is_a?(Symbol)
+
+      !name.empty?
+    end
+
+    def validate_property(**options)
+      return unless validate_property?(**options)
+
+      return if valid_property?(**options)
+
+      raise ArgumentError,
+        "invalid property name #{options[:property].inspect}",
+        caller(1..-1)
+    end
+
+    def validate_property?(property: nil, **_options)
+      !property.nil?
+    end
+  end
+end

data/lib/stannum/contracts/array_contract.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/types/array_type'
+require 'stannum/contracts'
+require 'stannum/contracts/tuple_contract'
+
+module Stannum::Contracts
+  # An ArrayContract defines constraints for an Array and its items.
+  #
+  # In order to match an ArrayContract, the object must be an instance of Array,
+  # and the items in the array at each index must match the item constraint
+  # defined for that index. If the :item_type option is set, each item must
+  # match that type or constraint. Finally, unless the :allow_extra_items option
+  # is set to true, the object must not have any extra items.
+  #
+  # @example Creating A Contract With Item Constraints
+  #   third_base_constraint = Stannum::Constraint.new do |actual|
+  #     actual == "I Don't Know"
+  #   end
+  #   array_contract = Stannum::Contracts::ArrayContract.new do
+  #     item { |actual| actual == 'Who' }
+  #     item { |actual| actual == 'What' }
+  #     item third_base_constraint
+  #   end
+  #
+  # @example With A Non-Array Object
+  #   array_contract.matches?(nil) #=> false
+  #   errors = array_contract.errors_for(nil)
+  #   errors.to_a
+  #   #=> [
+  #     {
+  #       type:    'stannum.constraints.type',
+  #       data:    { required: true, type: Array },
+  #       message: nil,
+  #       path:    []
+  #     }
+  #   ]
+  #
+  # @example With An Object With Missing Items
+  #   array_contract.matches?(['Who']) #=> false
+  #   errors = array_contract.errors_for(['Who'])
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'stannum.constraints.invalid', data: {}, path: [1], message: nil },
+  #     { type: 'stannum.constraints.invalid', data: {}, path: [2], message: nil }
+  #   ]
+  #
+  # @example With An Object With Incorrect Items
+  #   array_contract.matches?(['What', 'What', "I Don't Know"]) #=> false
+  #   errors = array_contract.errors_for(['What', 'What', "I Don't Know"])
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'stannum.constraints.invalid', data: {}, path: [0], message: nil }
+  #   ]
+  #
+  # @example With An Object With Valid Items
+  #   array_contract.matches?(['Who', 'What', "I Don't Know"]) #=> true
+  #   errors = array_contract.errors_for(['What', 'What', "I Don't Know"])
+  #   errors.to_a #=> []
+  #
+  # @example With An Object With Extra Items
+  #   array_contract.matches?(['Who', 'What', "I Don't Know", 'Tomorrow', 'Today']) #=> false
+  #   errors = array_contract.errors_for(['Who', 'What', "I Don't Know", 'Tomorrow', 'Today'])
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'stannum.constraints.tuples.extra_items', data: {}, path: [3], message: nil },
+  #     { type: 'stannum.constraints.tuples.extra_items', data: {}, path: [4], message: nil }
+  #   ]
+  class ArrayContract < Stannum::Contracts::TupleContract
+    # @param allow_extra_items [true, false] If false, then a tuple with extra
+    #   items after the last expected item will not match the contract.
+    # @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
+    #   contract. Defaults to an empty Hash.
+    def initialize(allow_extra_items: false, item_type: nil, **options, &block)
+      super(
+        allow_extra_items: allow_extra_items,
+        item_type:         item_type,
+        **options,
+        &block
+      )
+    end
+
+    # @return [Stannum::Constraints::Base, nil] the expected type for the items
+    #   in the array.
+    def item_type
+      options[:item_type]
+    end
+
+    # (see Stannum::Contracts::Base#with_options)
+    def with_options(**options)
+      return super unless options.key?(:item_type)
+
+      raise ArgumentError, "can't change option :item_type"
+    end
+
+    private
+
+    def add_type_constraint
+      add_constraint(
+        Stannum::Constraints::Types::ArrayType.new(item_type: item_type),
+        sanity: true
+      )
+    end
+  end
+end