stannum 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74ab0240c5b4e242ba1f5dd6deb9724bb32ee6f310fbda553a2e0962fdfa7259
-  data.tar.gz: e2eac42708bd5b00dbd9a633ab8a9ecd13d4198a34754cd3149349a2d34c267d
+  metadata.gz: b13aa2cda5a99f544b2e7c281147f51b4e4fa02e394e4b6d017dcc2b1f03705d
+  data.tar.gz: e84dc0c10ccfd8989dcec729c485136c099257079df57cb44e82befb42ebf9b8
 SHA512:
-  metadata.gz: f2fd1eada7dd26a9fa0f62a93b59c781c89d0aa638efe27869f45d1421fdf2e83a50bcd2c75ed86e4e3350907c00c86f499c4663a93082c599e38147a8ea39a7
-  data.tar.gz: 33060d922ae97025d104e372f1d42e6616bc30f03156eff19c904e407c9b4db56475d6acad7ff322edba6949616a163c3817c60cc7a539ef4d631a4a389bc99a
+  metadata.gz: bd159ef522b377cb71e4ebc58d8e46987906a1b3a36a5e905965a5cef9dfcf09b3d3b6818519659a05a19b894b516af8d37ee17a60beb4c72fe4a5df04b2b97d
+  data.tar.gz: 806b0a8e067afee2185ba5164d85127543f4e3e821a2ca5582afa13135e6f1b4469f9c5cfb6461bfe3f376e17ec9d2c4580780f3b89d574764856593a660b763

data/CHANGELOG.md

@@ -1,9 +1,34 @@
 # Changelog
 
+## 0.3.0
+
+### Constraints
+
+- Implemented `Stannum::Constraints::Properties::MatchProperty`
+- Implemented `Stannum::Constraints::Properties::DoNotMatchProperty`
+
+### Contracts
+
+- Added `#concat` to `Stannum::Contracts::Builder`.
+
+### Entities
+
+Implemented `Stannum::Entity`, a replacement for the existing `Stannum::Struct`.
+
+Entitise are largely identical to structs, except for the constructor signature - entities require properties to be passed as keyword parameters, rather than as an attributes hash. Entities (and now Structs) are defined using composable modules.
+
+- Implemented `Stannum::Entities::Attributes`.
+- Implemented `Stannum::Entities::Constraints`.
+- Implemented `Stannum::Entities::Properties`.
+
+`Stannum::Struct` is now deprecated, and will be removed in a future release.
+
 ## 0.2.0
 
 ### Constraints
 
+#### Parameter Constraints
+
 - Implemented `Stannum::Constraints::Parameters::ExtraArguments`
 - Implemented `Stannum::Constraints::Parameters::ExtraKeywords`
 

data/README.md

@@ -7,7 +7,7 @@ Stannum defines the following objects:
 - [Constraints](#constraints): A validator object that responds to `#match`, `#matches?` and `#errors_for` for a given object.
 - [Contracts](#contracts): A collection of constraints about an object or its properties. Obeys the `Constraint` interface.
 - [Errors](#errors): Data object for storing validation errors. Supports arbitrary nesting of errors.
-- [Structs](#structs): Defines a mutable data object with a specified set of typed attributes.
+- [Entities](#entities): Defines a mutable data object with a specified set of typed attributes.
 
 ## About
 
@@ -17,11 +17,11 @@ First and foremost, Stannum provides you with the tools to validate your data. U
 
 Finally, you can combine your constraints into a `Stannum::Contract` to combine multiple validations of your object and its properties. Stannum provides pre-defined contracts for asserting on objects, `Array`s, `Hash`es, and even method parameters.
 
-Stannum also defines the `Stannum::Struct` module for defining structured data entities that are not tied to any framework or datastore. Stannum structs have more functionality and a friendlier interface than a core library `Struct`, provide more structure than a `Hash` or hash-like object (such as an `OpenStruct` or `Hashie::Mash`), and are completely independent from the source of the data. Need to load seed data from a YAML configuration file, perform operations in a SQL database, cross-reference with a MongoDB data store, and use an in-memory data array for lightning-fast tests? A `Stannum::Struct` won't fight you every step of the way.
+Stannum also defines the `Stannum::Entity` module for defining structured data entities that are not tied to any framework or datastore. Stannum entities have more functionality and a friendlier interface than a core library `Struct`, provide more structure than a `Hash` or hash-like object (such as an `OpenStruct` or `Hashie::Mash`), and are completely independent from the source of the data. Need to load seed data from a YAML configuration file, perform operations in a SQL database, cross-reference with a MongoDB data store, and use an in-memory data array for lightning-fast tests? A `Stannum::Entity` won't fight you every step of the way.
 
 ### Why Stannum?
 
-Stannum is not tied to any framework. You can create constraints and contracts to validate Ruby objects and Structs, data structures such as Arrays, Hashes, and Sets, and even framework objects such as `ActiveRecord::Model`s and `Mongoid::Document`s.
+Stannum is not tied to any framework. You can create constraints and contracts to validate Ruby objects and Entities, data structures such as Arrays, Hashes, and Sets, and even framework objects such as `ActiveRecord::Model`s and `Mongoid::Document`s.
 
 Still, most projects and applications use one framework to handle their data. Why use Stannum constraints?
 
@@ -33,7 +33,7 @@ Still, most projects and applications use one framework to handle their data. Wh
 
 ### Compatibility
 
-Stannum is tested against Ruby (MRI) 2.6 through 3.0.
+Stannum is tested against Ruby (MRI) 2.7 through 3.2.
 
 ### Documentation
 
@@ -331,7 +331,7 @@ contract.does_not_match?({ color: 'blue', shape: 'square'})
 
 Note that for an object that partially matches the contract, both `#matches?` and `#does_not_match?` methods will return false. If you want to check whether **any** of the constraints do not match the object, use the `#matches?` method and apply the `!` boolean negation operator (or switch from an `if` to an `unless`).
 
-#### Property Constraints
+#### Constraining Properties
 
 Constraints can also define constraints on the *properties* of the matched object. This is a powerful feature for defining validations on objects and nested data structures. To define a property constraint, use the `property` macro in a contract constructor block, or use the `#add_property_constraint` method on an existing contract.
 
@@ -725,16 +725,20 @@ errors.first.message
 
 Stannum uses the strategy pattern to determine how error messages are generated. You can pass the `strategy:` keyword to `#with_messages` to force Stannum to use the specified strategy, or set the `Stannum::Messages.strategy` property to define the default for your application. The default strategy for Stannum uses an I18n-like configuration file to define messages based on the type and optionally the data for each error.
 
-<a id="structs"></a>
+<a id="entities"></a>
 
-### Structs
+### Entities
 
-While constraints and contracts are used to validate data, structs are used to define and structure that data. Each `Stannum::Struct` contains a specific set of attributes, and each attribute has a type definition that is a `Class` or `Module` or the name of a Class or Module.
+While constraints and contracts are used to validate data, entities are used to define and structure that data. Each `Stannum::Entity` contains a specific set of attributes, and each attribute has a type definition that is a `Class` or `Module` or the name of a Class or Module.
 
-Structs are defined by creating a new class and including `Stannum::Struct`:
+Entities are defined by creating a new class and including `Stannum::Entity`:
 
 ```ruby
+require 'stannum'
+
 class Gadget
+  include Stannum::Entity
+
   attribute :name,        String
   attribute :description, String,  optional: true
   attribute :quantity,    Integer, default:  0
@@ -763,21 +767,21 @@ gadget[:description]
 
 Our `Gadget` class has three attributes: `#name`, `#description`, and `#quantity`, which we are defining using the `.attribute` class method.
 
-We can initialize a gadget with values by passing the desired attributes to `.new`. We can read or write the attributes using either dot `.` notation or `#[]` notation. Finally, we can access all of a struct's attributes and values using the `#attributes` method.
+We can initialize a gadget with values by passing the desired attributes to `.new`. We can read or write the attributes using either dot `.` notation or `#[]` notation. Finally, we can access all of a entity's attributes and values using the `#attributes` method.
 
-`Stannum::Struct` defines a number of helper methods for interacting with a struct's attributes:
+`Stannum::Entity` defines a number of helper methods for interacting with a entity's attributes:
 
 - `#[](attribute)`: Returns the value of the given attribute.
 - `#[]=(attribute, value)`: Writes the given value to the given attribute.
-- `#assign_attributes(values)`: Updates the struct's attributes using the given values. If an attribute is not given, that value is unchanged.
+- `#assign_attributes(values)`: Updates the entity's attributes using the given values. If an attribute is not given, that value is unchanged.
 - `#attributes`: Returns a hash containing the attribute keys and values.
-- `#attributes=(values)`: Sets the struct's attributes to the given values. If an attribute is not given, that attribute is set to `nil`.
+- `#attributes=(values)`: Sets the entity's attributes to the given values. If an attribute is not given, that attribute is set to `nil`.
 
-For all of the above methods, if a given attribute is invalid or the attribute is not defined on the struct, an `ArgumentError` will be raised.
+For all of the above methods, if a given attribute is invalid or the attribute is not defined on the entity, an `ArgumentError` will be raised.
 
 #### Attributes
 
-A struct's attributes are defined using the `.attribute` class method, and can be accessed and enumerated using the `.attributes` class method on the struct class or via the `::Attributes` constant. Internally, each attribute is represented by a `Stannum::Attribute` instance, which stores the attribute's `:name`, `:type`, and `:attributes`.
+A entity's attributes are defined using the `.attribute` class method, and can be accessed and enumerated using the `.attributes` class method on the entity class or via the `::Attributes` constant. Internally, each attribute is represented by a `Stannum::Attribute` instance, which stores the attribute's `:name`, `:type`, and `:attributes`.
 
 ```ruby
 Gadget::Attributes
@@ -796,11 +800,11 @@ Gadget.attributes[:quantity].options
 
 ##### Default Values
 
-Structs can define default values for attributes by passing a `:default` value to the `.attribute` call.
+Entities can define default values for attributes by passing a `:default` value to the `.attribute` call.
 
 ```ruby
 class LightsCounter
-  include Stannum::Struct
+  include Stannum::Entity
 
   attribute :count, Integer, default: 4
 end
@@ -811,11 +815,11 @@ LightsCounter.new.count
 
 ##### Optional Attributes
 
-Struct classes can also mark attributes as `optional`. When a struct is validated (see [Validation](#structs-validation), below), optional attributes will pass with a value of `nil`.
+Entity classes can also mark attributes as `optional`. When an entity is validated (see [Validation](#entities-validation), below), optional attributes will pass with a value of `nil`.
 
 ```ruby
 class WhereWeAreGoing
-  include Stannum::Struct
+  include Stannum::Entity
 
   attribute :roads, Object, optional: true
 end
@@ -823,11 +827,11 @@ end
 
 `Stannum` supports both `:optional` and `:required` as keys. Passing either `optional: true` or `required: false` will mark the attribute as optional. Attributes are required by default.
 
-<a id="structs-validation"></a>
+<a id="entities-validation"></a>
 
 #### Validation
 
-Each `Stannum::Struct` automatically generates a contract that can be used to validate instances of the struct class. The contract can be accessed using the `.contract` class method or via the `::Contract` constant.
+Each `Stannum::Entity` automatically generates a contract that can be used to validate instances of the entity class. The contract can be accessed using the `.contract` class method or via the `::Contract` constant.
 
 ```ruby
 class Gadget
@@ -1091,6 +1095,66 @@ constraint.matches?(:a_symbol)
 #=> true
 ```
 
+#### Property Constraints
+
+Property constraints match against the properties of the object.
+
+**Do Not Match Property Constraint**
+
+Matches if none of the values of the given properties are equal to the value of the expected property.
+
+```ruby
+UpdatePassword = Struct.new(:old_password, :new_password)
+constraint    = Stannum::Constraints::Properties::DoNotMatchProperty.new(
+  :old_password,
+  :new_password
+)
+
+params = UpdatePassword.new('tronlives', 'ifightfortheusers')
+constraint.matches?(params)
+#=> true
+
+params = UpdatePassword.new('tronlives', 'tronlives')
+constraint.matches?(params)
+#=> false
+constraint.errors_for(params)
+#=> [
+  {
+    path: [:confirmation],
+    type: 'stannum.constraints.is_equal_to',
+    data: { expected: '[FILTERED]', actual: '[FILTERED]' }
+  }
+]
+```
+
+**Match Property Constraint**
+
+Matches if all the values of the given properties are equal to the value of the expected property.
+
+```ruby
+ConfirmPassword = Struct.new(:password, :confirmation)
+constraint    = Stannum::Constraints::Properties::MatchProperty.new(
+  :password,
+  :confirmation
+)
+
+params = ConfirmPassword.new('tronlives', 'ifightfortheusers')
+constraint.matches?(params)
+#=> false
+constraint.errors_for(params)
+#=> [
+  {
+    path: [:confirmation],
+    type: 'stannum.constraints.is_not_equal_to',
+    data: { expected: '[FILTERED]', actual: '[FILTERED]' }
+  }
+]
+
+params = ConfirmPassword.new('tronlives', 'tronlives')
+constraint.matches?(params)
+#=> true
+```
+
 #### Type Constraints
 
 Stannum also defines a set of built-in type constraints. Unless otherwise noted, these are identical to a [Type Constraint](#builtin-constraints-type) with the given Class.

data/lib/stannum/constraints/hashes/extra_keys.rb

@@ -6,12 +6,17 @@ require 'stannum/support/coercion'
 module Stannum::Constraints::Hashes
   # Constraint for validating the keys of a hash-like object.
   #
+  # When using this constraint, the keys must be strings or symbols, and the
+  # hash keys must be of the same type. A constraint configured with string keys
+  # will not match a hash with symbol keys, and vice versa.
+  #
   # @example
-  #   keys       = %[fuel mass size]
+  #   keys       = %i[fuel mass size]
   #   constraint = Stannum::Constraints::Hashes::ExpectedKeys.new(keys)
   #
   #   constraint.matches?({})                                #=> true
   #   constraint.matches?({ fuel: 'Monopropellant' })        #=> true
+  #   constraint.matches?({ 'fuel' => 'Monopropellant' })    #=> false
   #   constraint.matches?({ electric: true, fuel: 'Xenon' }) #=> false
   #   constraint.matches?({ fuel: 'LF/O', mass: '1 ton', size: 'Medium' })
   #   #=> true
@@ -68,7 +73,7 @@ module Stannum::Constraints::Hashes
       errors
     end
 
-    # @return [Array] the expected keys.
+    # @return [Set] the expected keys.
     def expected_keys
       keys = options[:expected_keys]
 

data/lib/stannum/constraints/hashes/indifferent_extra_keys.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/hashes'
+require 'stannum/constraints/hashes/extra_keys'
+
+module Stannum::Constraints::Hashes
+  # Constraint for validating the keys of an indifferent hash-like object.
+  #
+  # When using this constraint, the keys must be strings or symbols, but it does
+  # not matter which - a constraint configured with string keys will match a
+  # hash with symbol keys, and vice versa.
+  #
+  # @example
+  #   keys       = %i[fuel mass size]
+  #   constraint = Stannum::Constraints::Hashes::ExpectedKeys.new(keys)
+  #
+  #   constraint.matches?({})                                #=> true
+  #   constraint.matches?({ fuel: 'Monopropellant' })        #=> true
+  #   constraint.matches?({ 'fuel' => 'Monopropellant' })    #=> true
+  #   constraint.matches?({ electric: true, fuel: 'Xenon' }) #=> false
+  #   constraint.matches?({ fuel: 'LF/O', mass: '1 ton', size: 'Medium' })
+  #   #=> true
+  #   constraint.matches?(
+  #     { fuel: 'LF', mass: '2 tons', nuclear: true, size: 'Medium' }
+  #   )
+  #   #=> false
+  class IndifferentExtraKeys < Stannum::Constraints::Hashes::ExtraKeys
+    # @return [Set] the expected keys.
+    def expected_keys
+      keys = options[:expected_keys]
+
+      return indifferent_keys_for(keys) unless keys.is_a?(Proc)
+
+      indifferent_keys_for(keys.call)
+    end
+
+    private
+
+    def indifferent_keys_for(keys)
+      Set.new(
+        keys.reduce([]) do |ary, key|
+          ary << key.to_s << key.intern
+        end
+      )
+    end
+  end
+end

data/lib/stannum/constraints/hashes.rb

@@ -5,7 +5,11 @@ require 'stannum/constraints'
 module Stannum::Constraints
   # Namespace for Hash-specific constraints.
   module Hashes
-    autoload :ExtraKeys,      'stannum/constraints/hashes/extra_keys'
-    autoload :IndifferentKey, 'stannum/constraints/hashes/indifferent_key'
+    autoload :ExtraKeys,
+      'stannum/constraints/hashes/extra_keys'
+    autoload :IndifferentExtraKeys,
+      'stannum/constraints/hashes/indifferent_extra_keys'
+    autoload :IndifferentKey,
+      'stannum/constraints/hashes/indifferent_key'
   end
 end

data/lib/stannum/constraints/properties/base.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/tools/toolbelt'
+
+require 'stannum/constraints/properties'
+
+module Stannum::Constraints::Properties
+  # Abstract base class for property constraints.
+  class Base < Stannum::Constraints::Base
+    # Default parameter names to filter out of errors.
+    FILTERED_PARAMETERS = %i[
+      passw
+      secret
+      token
+      _key
+      crypt
+      salt
+      certificate
+      otp
+      ssn
+    ].freeze
+
+    # @param property_names [Array<String, Symbol>] the name or names of the
+    #   properties to match.
+    # @param options [Hash<Symbol, Object>] configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    #
+    # @option options allow_empty [true, false] if true, will match against an
+    #   object with empty property values, such as an empty string.
+    # @option options allow_nil [true, false] if true, will match against an
+    #   object with nil property values.
+    def initialize(*property_names, **options)
+      @property_names = property_names
+
+      validate_property_names
+
+      super(
+        allow_empty:    !!options[:allow_empty],
+        allow_nil:      !!options[:allow_nil],
+        property_names: property_names,
+        **options
+      )
+    end
+
+    # @return [Array<String, Symbol>] the name or names of the properties to
+    #   match.
+    attr_reader :property_names
+
+    # @return [true, false] if true, will match against an object with empty
+    #   property values, such as an empty string.
+    def allow_empty?
+      options[:allow_empty]
+    end
+
+    # @return [true, false] if true, will match against an object with nil
+    #   property values.
+    def allow_nil?
+      options[:allow_nil]
+    end
+
+    private
+
+    def can_match_properties?(actual)
+      actual.respond_to?(:[])
+    end
+
+    def each_property(actual)
+      return to_enum(__method__, actual) unless block_given?
+
+      property_names.each do |property_name|
+        yield property_name, actual[property_name]
+      end
+    end
+
+    def empty?(value)
+      value.respond_to?(:empty?) && value.empty?
+    end
+
+    def filter_parameters?
+      return @filter_parameters unless @filter_parameters.nil?
+
+      filters = filtered_parameters.map { |param| Regexp.new(param.to_s) }
+
+      @filter_parameters =
+        property_names.any? do |property_name|
+          filters.any? { |filter| filter.match?(property_name.to_s) }
+        end
+    end
+
+    def filtered_parameters
+      return Rails.configuration.filter_parameters if defined?(Rails)
+
+      FILTERED_PARAMETERS
+    end
+
+    def invalid_object_errors(errors)
+      errors.add(
+        Stannum::Constraints::Signature::TYPE,
+        methods: %i[[]],
+        missing: %i[[]]
+      )
+    end
+
+    def skip_property?(value)
+      (allow_empty? && empty?(value)) || (allow_nil? && value.nil?)
+    end
+
+    def tools
+      SleepingKingStudios::Tools::Toolbelt.instance
+    end
+
+    def validate_property_names
+      if property_names.empty?
+        raise ArgumentError, "property names can't be empty"
+      end
+
+      property_names.each.with_index do |property_name, index|
+        tools
+          .assertions
+          .validate_name(property_name, as: "property name at #{index}")
+      end
+    end
+  end
+end

data/lib/stannum/constraints/properties/do_not_match_property.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints/properties'
+require 'stannum/constraints/properties/matching'
+
+module Stannum::Constraints::Properties
+  # Compares the properties of the given object with the specified property.
+  #
+  # If none of the property values equal the expected value, the constraint will
+  # match the object; otherwise, if there are any matching values, the
+  # constraint will not match.
+  #
+  # @example Using an Properties::Match constraint
+  #   UpdatePassword = Struct.new(:old_password, :new_password)
+  #   constraint    = Stannum::Constraints::Properties::DoNotMatchProperty.new(
+  #     :old_password,
+  #     :new_password
+  #   )
+  #
+  #   params = UpdatePassword.new('tronlives', 'ifightfortheusers')
+  #   constraint.matches?(params)
+  #   #=> true
+  #
+  #   params = UpdatePassword.new('tronlives', 'tronlives')
+  #   constraint.matches?(params)
+  #   #=> false
+  #   constraint.errors_for(params)
+  #   #=> [
+  #     {
+  #       path: [:confirmation],
+  #       type: 'stannum.constraints.is_equal_to',
+  #       data: { expected: '[FILTERED]', actual: '[FILTERED]' }
+  #     }
+  #   ]
+  class DoNotMatchProperty < Stannum::Constraints::Properties::Matching
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = Stannum::Constraints::Equality::TYPE
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = Stannum::Constraints::Equality::NEGATED_TYPE
+
+    # @return [true, false] true if the property values match the reference
+    #   property value; otherwise false.
+    def does_not_match?(actual)
+      return false unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+
+      return false if skip_property?(expected)
+
+      each_non_matching_property(
+        actual:      actual,
+        expected:    expected,
+        include_all: true
+      )
+        .none?
+    end
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      errors ||= Stannum::Errors.new
+
+      return invalid_object_errors(errors) unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+      matching = each_matching_property(actual: actual, expected: expected)
+
+      return generic_errors(errors) if matching.count.zero?
+
+      matching.each do |property_name, _|
+        errors[property_name].add(type, message: message)
+      end
+
+      errors
+    end
+
+    # @return [true, false] false if any of the property values match the
+    #   reference property value; otherwise true.
+    def matches?(actual)
+      return false unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+
+      return true if skip_property?(expected)
+
+      each_matching_property(actual: actual, expected: expected).none?
+    end
+    alias match? matches?
+
+    # (see Stannum::Constraints::Base#negated_errors_for)
+    def negated_errors_for(actual, errors: nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      errors ||= Stannum::Errors.new
+
+      return invalid_object_errors(errors) unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+      matching = each_non_matching_property(
+        actual:      actual,
+        expected:    expected,
+        include_all: true
+      )
+
+      return generic_errors(errors) if matching.count.zero?
+
+      matching.each do |property_name, value|
+        errors[property_name].add(
+          negated_type,
+          message:  negated_message,
+          expected: filter_parameters? ? '[FILTERED]' : expected_value(actual),
+          actual:   filter_parameters? ? '[FILTERED]' : value
+        )
+      end
+
+      errors
+    end
+  end
+end