stannum 0.2.0 → 0.4.0

data/lib/stannum/attribute.rb

@@ -4,16 +4,71 @@ require 'stannum'
 require 'stannum/support/optional'
 
 module Stannum
-  # Data object representing an attribute on a struct.
+  # Data object representing an attribute on an entity.
   class Attribute
     include Stannum::Support::Optional
 
+    # Builder class for defining attribute methods on an entity.
+    class Builder
+      # @param schema [Stannum::Schema] the attributes schema on which to define
+      #   methods.
+      def initialize(schema)
+        @schema = schema
+      end
+
+      # @return [Stannum::Schema] the attributes schema on which to define
+      #   methods.
+      attr_reader :schema
+
+      # Defines the reader and writer methods for the attribute.
+      #
+      # @param attribute [Stannum::Attribute]
+      def call(attribute)
+        define_reader(attribute)
+        define_writer(attribute)
+      end
+
+      private
+
+      def define_reader(attribute)
+        schema.define_method(attribute.reader_name) do
+          read_attribute(attribute.name, safe: false)
+        end
+      end
+
+      def define_writer(attribute) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+        assoc_name = attribute.association_name
+
+        schema.define_method(attribute.writer_name) do |value|
+          previous_value = read_attribute(attribute.name, safe: false)
+
+          return if previous_value == value
+
+          if attribute.foreign_key? && !previous_value.nil?
+            self
+              .class
+              .associations[assoc_name]
+              .remove_value(self, previous_value)
+          end
+
+          value = attribute.default_value_for(self) if value.nil?
+
+          write_attribute(attribute.name, value, safe: false)
+        end
+      end
+    end
+
     # @param name [String, Symbol] The name of the attribute. Converted to a
     #   String.
     # @param options [Hash, nil] Options for the attribute. Converted to a Hash
     #   with Symbol keys. Defaults to an empty Hash.
     # @param type [Class, Module, String] The type of the attribute. Can be a
     #   Class, a Module, or the name of a class or module.
+    #
+    # @option options [Object] :default The default value for the attribute.
+    #   Defaults to nil.
+    # @option options [Boolean] :primary_key true if the attribute represents
+    #   the primary key for the entity; otherwise false. Defaults to false.
     def initialize(name:, options:, type:)
       validate_name(name)
       validate_options(options)
@@ -35,6 +90,12 @@ module Stannum
     # @return [String] the name of the attribute type Class or Module.
     attr_reader :type
 
+    # @return [String] the name of the association if the attribute is a foreign
+    #   key; otherwise false.
+    def association_name
+      @options[:association_name]
+    end
+
     # @return [Object] the default value for the attribute, if any.
     def default
       @options[:default]
@@ -46,6 +107,29 @@ module Stannum
       !@options[:default].nil?
     end
 
+    # @param context [Object] the context object used to determinet the default
+    #   value.
+    #
+    # @return [Object] the value of the default attribute for the given context
+    #   object, if any.
+    def default_value_for(context)
+      return default unless default.is_a?(Proc)
+
+      default.arity.zero? ? default.call : default.call(context)
+    end
+
+    # @return [Boolean] true if the attribute represents the foreign key for an
+    #   association; otherwise false.
+    def foreign_key?
+      !!@options[:foreign_key]
+    end
+
+    # @return [Boolean] true if the attribute represents the primary key for the
+    #   entity; otherwise false.
+    def primary_key?
+      !!@options[:primary_key]
+    end
+
     # @return [Symbol] the name of the reader method for the attribute.
     def reader_name
       @reader_name ||= name.intern
@@ -82,13 +166,7 @@ module Stannum
     end
 
     def validate_name(name)
-      raise ArgumentError, "name can't be blank" if name.nil?
-
-      unless name.is_a?(String) || name.is_a?(Symbol)
-        raise ArgumentError, 'name must be a String or Symbol'
-      end
-
-      raise ArgumentError, "name can't be blank" if name.empty?
+      tools.assertions.validate_name(name, as: 'name')
     end
 
     def validate_options(options)

data/lib/stannum/constraints/base.rb

@@ -55,9 +55,7 @@ module Stannum::Constraints
     #
     # @return [Stannum::Constraints::Base] the cloned constraint.
     def clone(freeze: nil)
-      freeze = true if freeze.nil? && RUBY_VERSION <= '3.0.0'
-
-      super(freeze: freeze).copy_properties(self)
+      super.copy_properties(self)
     end
 
     # Checks that the given object does not match the constraint.
@@ -80,7 +78,7 @@ module Stannum::Constraints
     #   or behavior, otherwise true.
     #
     # @see #matches?
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       !matches?(actual)
     end
 
@@ -118,7 +116,7 @@ module Stannum::Constraints
     # @see #matches?
     # @see #negated_errors_for
     def errors_for(actual, errors: nil) # rubocop:disable Lint/UnusedMethodArgument
-      (errors || Stannum::Errors.new).add(type, message: message)
+      (errors || Stannum::Errors.new).add(type, message:)
     end
 
     # Checks the given object against the constraint and returns errors, if any.

data/lib/stannum/constraints/enum.rb

@@ -26,7 +26,7 @@ module Stannum::Constraints
     def initialize(first, *rest, **options)
       expected_values = rest.unshift(first)
 
-      super(expected_values: expected_values, **options)
+      super(expected_values:, **options)
 
       @matching_values = Set.new(expected_values)
     end

data/lib/stannum/constraints/equality.rb

@@ -27,7 +27,7 @@ module Stannum::Constraints
     def initialize(expected_value, **options)
       @expected_value = expected_value
 
-      super(expected_value: expected_value, **options)
+      super(expected_value:, **options)
     end
 
     # @return [Object] the expected object.

data/lib/stannum/constraints/format.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require 'stannum/constraints'
+
+module Stannum::Constraints
+  # A Format constraint asserts the value is a string matching the given format.
+  #
+  # @example Using a Format constraint with a String format.
+  #   format = 'Greetings'
+  #   constraint = Stannum::Constraints::Format.new(format)
+  #
+  #   constraint.matches?(nil)                    #=> false
+  #   constraint.matches?('Hello, world')         #=> false
+  #   constraint.matches?('Greetings, programs!') #=> true
+  #
+  # @example Using a Format constraint with a Regex format.
+  #   format = /\AGreetings/
+  #   constraint = Stannum::Constraints::Format.new(format)
+  #
+  #   constraint.matches?(nil)                    #=> false
+  #   constraint.matches?('Hello, world')         #=> false
+  #   constraint.matches?('Greetings, programs!') #=> true
+  class Format < Stannum::Constraints::Base
+    # The :type of the error generated for a matching object.
+    NEGATED_TYPE = 'stannum.constraints.matches_format'
+
+    # The :type of the error generated for a non-matching object.
+    TYPE = 'stannum.constraints.does_not_match_format'
+
+    # @param expected_format [Regex, String] The expected object.
+    # @param options [Hash<Symbol, Object>] Configuration options for the
+    #   constraint. Defaults to an empty Hash.
+    def initialize(expected_format, **options)
+      @expected_format = expected_format
+
+      super(expected_format:, **options)
+    end
+
+    # @return [Regex, String] the expected format.
+    attr_reader :expected_format
+
+    # (see Stannum::Constraints::Base#errors_for)
+    def errors_for(actual, errors: nil)
+      return super if type_constraint.matches?(actual)
+
+      type_constraint.errors_for(actual, errors:)
+    end
+
+    # Checks that the object is a string with the expected format.
+    #
+    # @return [true, false] true if the object is a string with the expected
+    #   format, otherwise false.
+    #
+    # @see Stannum::Constraint#matches?
+    def matches?(actual)
+      return false unless type_constraint.matches?(actual)
+
+      if expected_format.is_a?(String)
+        actual.include?(expected_format)
+      else
+        actual.match?(expected_format)
+      end
+    end
+    alias match? matches?
+
+    private
+
+    def type_constraint
+      @type_constraint ||= Stannum::Constraints::Type.new(String)
+    end
+  end
+end

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
@@ -33,19 +38,14 @@ module Stannum::Constraints::Hashes
     def initialize(expected_keys, **options)
       validate_expected_keys(expected_keys)
 
-      expected_keys =
-        if expected_keys.is_a?(Array)
-          Set.new(expected_keys)
-        else
-          expected_keys
-        end
+      expected_keys = Set.new(expected_keys) if expected_keys.is_a?(Array)
 
-      super(expected_keys: expected_keys, **options)
+      super(expected_keys:, **options)
     end
 
     # @return [true, false] true if the object responds to #[] and #keys and the
     #   object has at least one key that is not in expected_keys.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       return false unless hash?(actual)
 
       !(Set.new(actual.keys) <= expected_keys) # rubocop:disable Style/InverseMethods
@@ -56,19 +56,19 @@ module Stannum::Constraints::Hashes
       errors ||= Stannum::Errors.new
 
       unless actual.respond_to?(:keys)
-        return add_invalid_hash_error(actual: actual, errors: errors)
+        return add_invalid_hash_error(actual:, errors:)
       end
 
       each_extra_key(actual) do |key, value|
         key = Stannum::Support::Coercion.error_key(key)
 
-        errors[key].add(type, value: value)
+        errors[key].add(type, value:)
       end
 
       errors
     end
 
-    # @return [Array] the expected keys.
+    # @return [Set] the expected keys.
     def expected_keys
       keys = options[:expected_keys]
 
@@ -91,7 +91,7 @@ module Stannum::Constraints::Hashes
     def add_invalid_hash_error(actual:, errors:)
       Stannum::Constraints::Signature
         .new(:keys)
-        .errors_for(actual, errors: errors)
+        .errors_for(actual, errors:)
     end
 
     def each_extra_key(actual)

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/identity.rb

@@ -26,7 +26,7 @@ module Stannum::Constraints
     def initialize(expected_value, **options)
       @expected_value = expected_value
 
-      super(expected_value: expected_value, **options)
+      super(expected_value:, **options)
     end
 
     # @return [Object] the expected object.

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:,
+        **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) # rubocop:disable Naming/PredicatePrefix
+      return false unless can_match_properties?(actual)
+
+      expected = expected_value(actual)
+
+      return false if skip_property?(expected)
+
+      each_non_matching_property(
+        actual:,
+        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:, expected:)
+
+      return generic_errors(errors) if matching.none?
+
+      matching.each do |property_name, _| # rubocop:disable Style/HashEachMethods
+        errors[property_name].add(type, 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:, 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:,
+        expected:,
+        include_all: true
+      )
+
+      return generic_errors(errors) if matching.none?
+
+      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