stannum 0.1.0

data/lib/stannum/contracts/definition.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'stannum/contracts'
+
+module Stannum::Contracts
+  # Struct that encapsulates a constraint definition on a contract.
+  class Definition
+    # @param attributes [Hash] The attributes for the definition.
+    # @option attributes [Stannum::Constraints::Base] :constraint The constraint
+    #   to define for the contract.
+    # @option attributes [Stannum::Contracts::Base] :contract The contract for
+    #   which the constraint is defined.
+    # @option attributes [Hash<Symbol, Object>] :options The options for the
+    #   constraint.
+    def initialize(attributes = {})
+      attributes.each do |key, value|
+        send(:"#{key}=", value)
+      end
+    end
+
+    # @!attribute [rw] constraint
+    #   @return [Stannum::Constraints::Base] the defined constraint.
+    attr_accessor :constraint
+
+    # @!attribute [rw] contract
+    #   @return [Stannum::Contracts::Base] the contract containing the
+    #     constraint.
+    attr_accessor :contract
+
+    # @!attribute [rw] options
+    #   @return [Hash<Symbol, Object>] the options defined for the constraint.
+    attr_accessor :options
+
+    # Compares the other object with the definition.
+    #
+    # @param other [Object] The object to compare.
+    #
+    # @return [Boolean] true if the other object is a Definition with the same
+    #   attributes; otherwise false.
+    def ==(other)
+      other.is_a?(self.class) &&
+        other.constraint == constraint &&
+        other.contract.equal?(contract) &&
+        other.options == options
+    end
+
+    # Indicates whether the defined constraint is inherited via concatenation.
+    #
+    # @return [Boolean] true if options[:concatenatable] is set to a truthy
+    #   value; otherwise false.
+    def concatenatable?
+      !!options.fetch(:concatenatable, true)
+    end
+
+    # @return [nil, String, Symbol, Array<String, Symbol>] the property scope of
+    #   the constraint.
+    def property
+      options[:property]
+    end
+
+    # @return [nil, String, Symbol, Array<String, Symbol>] the property name of
+    #   the constraint, used for generating errors. If not given, defaults to
+    #   the value of #property.
+    def property_name
+      options.fetch(:property_name, options[:property])
+    end
+
+    # @return [Boolean] true if options[:sanity] is set to a truthy value;
+    #   otherwise false.
+    def sanity?
+      !!options[:sanity]
+    end
+  end
+end

data/lib/stannum/contracts/hash_contract.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require 'stannum/contracts'
+require 'stannum/contracts/map_contract'
+require 'stannum/support/coercion'
+
+module Stannum::Contracts
+  # A HashContract defines constraints on an hash's values.
+  #
+  # @example Creating A Hash Contract
+  #   hash_contract = Stannum::Contracts::HashContract.new
+  #
+  #   hash_contract.add_constraint(
+  #     negated_type:  'example.is_boolean',
+  #     property:      :ok,
+  #     property_type: :key,
+  #     type:          'example.is_not_boolean'
+  #   ) { |actual| actual == true || actual == false }
+  #   hash_contract.add_constraint(
+  #     Stannum::Constraints::Type.new(Hash),
+  #     property:      :data,
+  #     property_type: :key,
+  #   )
+  #   hash_contract.add_constraint(
+  #     Stannum::Constraints::Presence.new,
+  #     property:      :signature,
+  #     property_type: :key,
+  #   )
+  #
+  # @example With A Non-Hash Object
+  #   hash_contract.matches?(nil) #=> false
+  #   errors = hash_contract.errors_for(nil)
+  #   #=> [{ type: 'is_not_type', data: { type: Hash }, path: [], message: nil }]
+  #
+  #   hash_contract.does_not_match?(nil)          #=> true
+  #   hash_contract.negated_errors_for?(nil).to_a #=> []
+  #
+  # @example With A Hash That Matches None Of The Key Constraints
+  #   hash_contract.matches?({}) #=> false
+  #   errors = hash_contract.errors_for({})
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_not_boolean', data: {}, path: [:ok], message: nil },
+  #     { type: 'is_not_type', data: { type: Hash }, path: [:data], message: nil },
+  #     { type: 'absent', data: {}, path: [:signature], message: nil }
+  #   ]
+  #
+  #   hash_contract.does_not_match?({}) #=> false
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_type', data: { type: Hash }, path: [], message: nil }
+  #   ]
+  #
+  # @example With A Hash That Matches Some Of The Key Constraints
+  #   hash = { ok: true, signature: '' }
+  #   hash_contract.matches?(hash) #=> false
+  #   errors = hash_contract.errors_for(hash)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_not_type', data: { type: Hash }, path: [:data], message: nil },
+  #     { type: 'absent', data: {}, path: [:signature], message: nil }
+  #   ]
+  #
+  #   hash_contract.does_not_match?(hash) #=> false
+  #   errors = hash_contract.negated_errors_for?(hash)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_type', data: { type: Hash }, path: [], message: nil },
+  #     { type: 'is_boolean', data: {}, path: [:ok], message: nil }
+  #   ]
+  #
+  # @example With A Hash That Matches All Of The Key Constraints
+  #   hash = { ok: true, data: {}, signature: 'abc' }
+  #   hash_contract.matches?(hash)        #=> true
+  #   hash_contract.errors_for(hash).to_a #=> []
+  #
+  #   hash_contract.does_not_match?(hash) #=> false
+  #   errors = hash_contract.negated_errors_for?(hash)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_type', data: { type: Hash }, path: [], message: nil },
+  #     { type: 'is_boolean', data: {}, path: [:ok], message: nil },
+  #     { type: 'present', data: {}, path: [:signature], message: nil },
+  #   ]
+  class HashContract < Stannum::Contracts::MapContract
+    # @param allow_extra_keys [true, false] If true, the contract will match
+    #   hashes with keys that are not constrained by the contract.
+    # @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
+    #   contract. Defaults to an empty Hash.
+    def initialize(
+      allow_extra_keys: false,
+      key_type:         nil,
+      value_type:       nil,
+      **options,
+      &block
+    )
+      super(
+        allow_extra_keys: allow_extra_keys,
+        key_type:         key_type,
+        value_type:       value_type,
+        **options,
+        &block
+      )
+    end
+
+    # @return [Stannum::Constraints::Base, Class, nil] the expected type for the
+    #   keys in the Hash, if any.
+    def key_type
+      options[:key_type]
+    end
+
+    # @return [Stannum::Constraints::Base, Class, nil] the expected type for the
+    #   values in the Hash, if any.
+    def value_type
+      options[:value_type]
+    end
+
+    private
+
+    def add_type_constraint
+      add_constraint(
+        Stannum::Constraints::Types::HashType.new(
+          key_type:   key_type,
+          value_type: value_type
+        ),
+        sanity: true
+      )
+    end
+  end
+end

data/lib/stannum/contracts/indifferent_hash_contract.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/hashes/indifferent_key'
+require 'stannum/contracts'
+
+module Stannum::Contracts
+  # An IndifferentHashContract defines constraints on an hash's values.
+  #
+  # The keys for an IndifferentHashContract must be either strings or symbols.
+  # The type of key is ignored when matching - a hash with a string key will
+  # match an expected symbol key and vice versa.
+  #
+  # @example Creating An Indifferent Hash Contract
+  #   hash_contract = Stannum::Contracts::HashContract.new
+  #   hash_contract.add_constraint(
+  #     Stannum::Constraints::Presence.new,
+  #     property:      :data,
+  #     property_type: :key,
+  #   )
+  #
+  # @example With A Non-Hash Object
+  #   hash_contract.matches?(nil) #=> false
+  #   errors = hash_contract.errors_for(nil)
+  #   #=> [{ type: 'is_not_type', data: { type: Hash }, path: [], message: nil }]
+  #
+  # @example With An Empty Hash
+  #   hash_contract.matches?({}) #=> false
+  #   errors = hash_contract.errors_for({})
+  #   #=> [{ type: 'absent', data: {}, path: [:data], message: nil }]
+  #
+  # @example With A Hash With String Keys
+  #   hash = { 'data' => {} }
+  #   hash_contract.matches?(hash)   #=> true
+  #   hash_contract.errors_for(hash) #=> []
+  #
+  # @example With A Hash With Symbol Keys
+  #   hash = { data: {} }
+  #   hash_contract.matches?(hash)   #=> true
+  #   hash_contract.errors_for(hash) #=> []
+  class IndifferentHashContract < HashContract
+    # @param allow_extra_keys [true, false] If true, the contract will match
+    #   hashes with keys that are not constrained by the contract.
+    # @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
+    #   contract. Defaults to an empty Hash.
+    def initialize(
+      allow_extra_keys: false,
+      value_type:       nil,
+      **options,
+      &block
+    )
+      super(
+        allow_extra_keys: allow_extra_keys,
+        key_type:         Stannum::Constraints::Hashes::IndifferentKey.new,
+        value_type:       value_type,
+        **options,
+        &block
+      )
+    end
+
+    protected
+
+    def map_value(actual, **options)
+      return super unless options[:property_type] == :key
+
+      property = options[:property]
+
+      case property
+      when String
+        actual.fetch(property) { actual[property.intern] }
+      when Symbol
+        actual.fetch(property) { actual[property.to_s] }
+      end
+    end
+  end
+end

data/lib/stannum/contracts/map_contract.rb

@@ -0,0 +1,199 @@
+# frozen_string_literal: true
+
+require 'stannum/contracts'
+
+module Stannum::Contracts
+  # A MapContract defines constraints on an hash-like object's values.
+  #
+  # @example Creating A Map Contract
+  #   Response     = Struct.new(:ok, :data, :signature)
+  #   map_contract = Stannum::Contracts::MapContract.new
+  #
+  #   map_contract.add_constraint(
+  #     negated_type:  'example.is_boolean',
+  #     property:      :ok,
+  #     property_type: :key,
+  #     type:          'example.is_not_boolean'
+  #   ) { |actual| actual == true || actual == false }
+  #   map_contract.add_constraint(
+  #     Stannum::Constraints::Type.new(Hash),
+  #     property:      :data,
+  #     property_type: :key,
+  #   )
+  #   map_contract.add_constraint(
+  #     Stannum::Constraints::Presence.new,
+  #     property:      :signature,
+  #     property_type: :key,
+  #   )
+  #
+  # @example With A Non-Map Object
+  #   map_contract.matches?(nil) #=> false
+  #   errors = map_contract.errors_for(nil)
+  #   #=> [
+  #     {
+  #       type:    'stannum.constraints.does_not_have_methods',
+  #       data:    { methods: [:[], :each, :keys], missing: [:[], :each, :keys] },
+  #       message: nil,
+  #       path:    []
+  #     }
+  #   ]
+  #   map_contract.does_not_match?(nil)          #=> true
+  #   map_contract.negated_errors_for?(nil).to_a #=> []
+  #
+  # @example With An Object That Matches None Of The Key Constraints
+  #   response = Response.new
+  #   map_contract.matches?(response) #=> false
+  #   errors = map_contract.errors_for(response)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_not_boolean', data: {}, path: [:ok], message: nil },
+  #     { type: 'is_not_type', data: { type: Hash }, path: [:data], message: nil },
+  #     { type: 'absent', data: {}, path: [:signature], message: nil }
+  #   ]
+  #
+  # @example With An Object That Matches Some Of The Key Constraints
+  #   response = Response.new(true, nil, '')
+  #   map_contract.matches?(response) #=> false
+  #   errors = map_contract.errors_for(response)
+  #   errors.to_a
+  #   #=> [
+  #     { type: 'is_not_type', data: { type: Hash }, path: [:data], message: nil },
+  #     { type: 'absent', data: {}, path: [:signature], message: nil }
+  #   ]
+  #
+  # @example With An Object That Matches All Of The Key Constraints
+  #   response = Response.new(true, {}, 'abc')
+  #   hash_contract.matches?(response)        #=> true
+  #   hash_contract.errors_for(response).to_a #=> []
+  class MapContract < Stannum::Contract
+    # Builder class for defining item constraints for a Contract.
+    #
+    # This class should not be invoked directly. Instead, pass a block to the
+    # constructor for HashContract.
+    #
+    # @api private
+    class Builder < Stannum::Contract::Builder
+      # Defines a key constraint on the contract.
+      #
+      # @overload key(key, constraint, **options)
+      #   Adds the given constraint to the contract for the value at the given
+      #   key.
+      #
+      #   @param key [String, Symbol, Array<String, Symbol>] The key to
+      #     constrain.
+      #   @param constraint [Stannum::Constraint::Base] The constraint to add.
+      #   @param options [Hash<Symbol, Object>] Options for the constraint.
+      #
+      # @overload key(**options) { |value| }
+      #   Creates a new Stannum::Constraint object with the given block, and
+      #   adds that constraint to the contract for the value at the given key.
+      def key(property, constraint = nil, **options, &block)
+        self.constraint(
+          constraint,
+          property:      property,
+          property_type: :key,
+          **options,
+          &block
+        )
+      end
+    end
+
+    # @param allow_extra_keys [true, false] If true, the contract will match
+    #   hashes with keys that are not constrained by the contract.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   contract. Defaults to an empty Hash.
+    def initialize(
+      allow_extra_keys: false,
+      **options,
+      &block
+    )
+      super(
+        allow_extra_keys: allow_extra_keys,
+        **options,
+        &block
+      )
+    end
+
+    # Adds a key constraint to the contract.
+    #
+    # When the contract is called, the contract will find the value of the
+    # object for the given key.
+    #
+    # @param key [Integer] The key of the value 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 Stannum::Contract#add_constraint.
+    def add_key_constraint(key, constraint, sanity: false, **options)
+      add_constraint(
+        constraint,
+        property:      key,
+        property_type: :key,
+        sanity:        sanity,
+        **options
+      )
+    end
+
+    # @return [true, false] if true, the contract will match hashes with keys
+    #   that are not constrained by the contract.
+    def allow_extra_keys?
+      options[:allow_extra_keys]
+    end
+
+    # @return [Array] the list of keys expected by the key constraints.
+    def expected_keys
+      each_constraint.reduce([]) do |keys, definition|
+        next keys unless definition.options[:property_type] == :key
+
+        keys << definition.options.fetch(:property)
+      end
+    end
+
+    # (see Stannum::Contracts::Base#with_options)
+    def with_options(**options)
+      return super unless options.key?(:allow_extra_keys)
+
+      raise ArgumentError, "can't change option :allow_extra_keys"
+    end
+
+    protected
+
+    def map_value(actual, **options)
+      return super unless options[:property_type] == :key
+
+      actual[options[:property]]
+    end
+
+    private
+
+    def add_extra_keys_constraint
+      return if options[:allow_extra_keys]
+
+      keys = -> { expected_keys }
+
+      add_constraint(
+        Stannum::Constraints::Hashes::ExtraKeys.new(keys),
+        concatenatable: false
+      )
+    end
+
+    def add_type_constraint
+      add_constraint Stannum::Constraints::Signatures::Map.new, sanity: true
+    end
+
+    def define_constraints(&block)
+      add_type_constraint
+
+      add_extra_keys_constraint
+
+      super
+    end
+  end
+end

data/lib/stannum/contracts/parameters/arguments_contract.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'stannum/contracts/parameters'
+require 'stannum/support/coercion'
+
+module Stannum::Contracts::Parameters
+  # @api private
+  #
+  # An ArgumentsContract constrains the arguments given for a method.
+  class ArgumentsContract < Stannum::Contracts::TupleContract
+    # The :type of the error generated for extra arguments.
+    EXTRA_ARGUMENTS_TYPE = 'stannum.constraints.parameters.extra_arguments'
+
+    # Value used when arguments array does not have a value for the given index.
+    UNDEFINED = Object.new.freeze
+
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   contract. Defaults to an empty Hash.
+    def initialize(**options)
+      super(allow_extra_items: false, **options)
+    end
+
+    # Adds an argument constraint to the contract.
+    #
+    # Generates an argument constraint based on the given type. If the type is
+    # a constraint, then the given constraint will be copied with the given
+    # options and added for the argument at the index. If the type is a Class or
+    # a Module, then a Stannum::Constraints::Type constraint will be created
+    # with the given type and options and added for the argument.
+    #
+    # If the index is specified, then the constraint will be added for the
+    # argument at the specified index. If the index is not given, then the
+    # constraint will be applied to the next unconstrained argument. For
+    # example, the first argument constraint will be added for the argument at
+    # index 0, the second constraint for the argument at index 1, and so on.
+    #
+    # @param index [Integer, nil] The index of the argument. If not given, then
+    #   the next argument will be constrained with the type.
+    # @param type [Class, Module, Stannum::Constraints:Base] The expected type
+    #   of the argument.
+    # @param default [Boolean] If true, the argument has a default value, and
+    #   the constraint will ignore arguments with no value at that index.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    #
+    # @return [Stannum::Contracts::Parameters::ArgumentsContract] the contract.
+    def add_argument_constraint(index, type, default: false, **options)
+      index    ||= next_index
+      constraint = Stannum::Support::Coercion.type_constraint(type, **options)
+
+      add_index_constraint(index, constraint, default: !!default, **options)
+
+      self
+    end
+
+    # Sets a constraint for the variadic arguments.
+    #
+    # The given constraint must match the variadic arguments array as a whole.
+    # To constraint each individual item, use #set_variadic_item_constraint.
+    #
+    # @param constraint [Stannum::Constraints::Base] The constraint to add.
+    #   The variadic arguments (an array) as a whole must match the given
+    #   constraint.
+    # @param as [Symbol] A human-friendly reference for the additional
+    #   arguments. Used when generating errors. Should be the same name used in
+    #   the method definition.
+    #
+    # @return [self] the contract.
+    #
+    # @raise [RuntimeError] if the variadic arguments constraint is already set.
+    #
+    # @see #set_variadic_item_constraint
+    def set_variadic_constraint(constraint, as: nil)
+      raise 'variadic arguments constraint is already set' if allow_extra_items?
+
+      options[:allow_extra_items] = true
+
+      variadic_constraint.receiver = constraint
+
+      variadic_definition.options[:property_name] = as if as
+
+      self
+    end
+
+    # Sets a constraint for the variadic argument items.
+    #
+    # The given type or constraint must individually match each item (if any) in
+    # the variadic arguments. To constrain the variadic arguments as a whole,
+    # use #set_variadic_constraint.
+    #
+    # @param item_type [Stannum::Constraints::Base, Class, Module] The type or
+    #   constraint to add. If the type is a Class or Module, then it is
+    #   converted to a Stannum::Constraints::Type. Each item in the variadic
+    #   arguments must match the given constraint.
+    # @param as [Symbol] A human-friendly reference for the additional
+    #   arguments. Used when generating errors. Should be the same name used in
+    #   the method definition.
+    #
+    # @return [self] the contract.
+    #
+    # @raise [RuntimeError] if the variadic arguments constraint is already set.
+    #
+    # @see #set_variadic_constraint
+    def set_variadic_item_constraint(item_type, as: nil)
+      type       = coerce_item_type(item_type)
+      constraint = Stannum::Constraints::Types::ArrayType.new(item_type: type)
+
+      set_variadic_constraint(constraint, as: as)
+    end
+
+    protected
+
+    def add_errors_for(definition, value, errors)
+      return super unless value == UNDEFINED
+
+      super(definition, nil, errors)
+    end
+
+    def add_negated_errors_for(definition, value, errors)
+      return super unless value == UNDEFINED
+
+      super(definition, nil, errors)
+    end
+
+    def map_value(actual, **options)
+      return super unless options[:property_type] == :index
+
+      return super unless actual.is_a?(Array)
+
+      return super if options[:property] < actual.size
+
+      UNDEFINED
+    end
+
+    def match_constraint(definition, value)
+      return super unless value == UNDEFINED
+
+      definition.options[:default] ? true : super(definition, nil)
+    end
+
+    def match_negated_constraint(definition, value)
+      return super unless value == UNDEFINED
+
+      definition.options[:default] ? false : super(definition, nil)
+    end
+
+    private
+
+    attr_reader :variadic_constraint
+
+    attr_reader :variadic_definition
+
+    def add_extra_items_constraint
+      count = -> { expected_count }
+
+      @variadic_constraint = Stannum::Constraints::Delegator.new(
+        Stannum::Constraints::Tuples::ExtraItems.new(
+          count,
+          type: EXTRA_ARGUMENTS_TYPE
+        )
+      )
+
+      add_constraint @variadic_constraint
+
+      @variadic_definition = @constraints.last
+    end
+
+    def coerce_item_type(item_type)
+      Stannum::Support::Coercion.type_constraint(item_type, as: 'item type')
+    end
+
+    def next_index
+      index = -1
+
+      each_constraint do |definition|
+        next unless definition.options[:property_type] == :index
+        next unless definition.property.is_a?(Integer)
+
+        index = definition.property if definition.property > index
+      end
+
+      1 + index
+    end
+  end
+end