stannum 0.3.0 → 0.4.0

data/lib/stannum/entities/primary_key.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require 'stannum/entities'
+
+module Stannum::Entities
+  # Methods for defining and accessing an entity's primary key attribute.
+  module PrimaryKey
+    # Raised when adding a primary key to an entity that already has one.
+    class PrimaryKeyAlreadyExists < StandardError; end
+
+    # Raised when accessing a primary key for an entity that does not have one.
+    class PrimaryKeyMissing < StandardError; end
+
+    # Class methods to extend the class when including PrimaryKey.
+    module ClassMethods
+      # Defines a primary key attribute on the entity.
+      #
+      # @param attr_name [String, Symbol] The name of the attribute. Must be a
+      #   non-empty String or Symbol.
+      # @param attr_type [Class, String] The type of the attribute. Must be a
+      #   Class or Module, or the name of a class or module.
+      # @param options [Hash] Additional options for the attribute.
+      #
+      # @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.
+      #
+      # @return [Symbol] The attribute name as a symbol.
+      #
+      # @see Stannum::Entities::Attributes::ClassMethods#define_attribute.
+      def define_primary_key(attr_name, attr_type, **options)
+        if primary_key?
+          raise PrimaryKeyAlreadyExists,
+            "#{name} already defines primary key #{primary_key_name.inspect}"
+        end
+
+        attribute(attr_name, attr_type, **options, primary_key: true)
+      end
+
+      # @return [Stannum::Attribute] the primary key attribute.
+      #
+      # @raise [Stannum::Entities::PrimaryKey::PrimaryKeyMissing] if the entity
+      #   does not define a primary key.
+      def primary_key
+        primary_key =
+          attributes
+          .find { |_, attribute| attribute.primary_key? }
+          &.last
+
+        return primary_key if primary_key
+
+        raise PrimaryKeyMissing, "#{name} does not define a primary key"
+      end
+
+      # @return [Boolean] true if the entity class defines a primary key;
+      #   otherwise false.
+      def primary_key?
+        attributes.any? { |_, attribute| attribute.primary_key? }
+      end
+
+      # @return [String, nil] the name of the primary key attribute, or nil if
+      #   the entity does not define a primary key.
+      def primary_key_name
+        attributes
+          .find { |_, attribute| attribute.primary_key? }
+          &.last
+          &.name
+      end
+
+      # @return [Class, nil] the type of the primary key attribute, or nil if
+      #   the entity does not define a primary key.
+      def primary_key_type
+        attributes
+          .find { |_, attribute| attribute.primary_key? }
+          &.last
+          &.resolved_type
+      end
+
+      private
+
+      def included(other)
+        super
+
+        other.include(Stannum::Entities::PrimaryKey)
+      end
+    end
+
+    class << self
+      private
+
+      def included(other)
+        super
+
+        other.extend(self::ClassMethods)
+      end
+    end
+
+    # @return [Boolean] true if the entity class defines a primary key and if
+    #   the entity has a non-empty value for that attribute; otherwise false.
+    def primary_key?
+      return false unless self.class.primary_key?
+
+      value = attributes[self.class.primary_key_name]
+
+      return false if value.nil? || (value.respond_to?(:empty?) && value.empty?)
+
+      true
+    end
+
+    # @return [String] the name of the primary key attribute.
+    #
+    # @raise [Stannum::Entities::PrimaryKey::PrimaryKeyMissing] if the entity
+    #   does not define a primary key.
+    def primary_key_name
+      unless self.class.primary_key?
+        raise PrimaryKeyMissing, "#{self.class} does not define a primary key"
+      end
+
+      self.class.primary_key_name
+    end
+
+    # @return [Class] the type of the primary key attribute.
+    #
+    # @raise [Stannum::Entities::PrimaryKey::PrimaryKeyMissing] if the entity
+    #   does not define a primary key.
+    def primary_key_type
+      unless self.class.primary_key?
+        raise PrimaryKeyMissing, "#{self.class} does not define a primary key"
+      end
+
+      self.class.primary_key_type
+    end
+
+    # @return [Object] the current value of the primary key attribute.
+    #
+    # @raise [Stannum::Entities::PrimaryKey::PrimaryKeyMissing] if the entity
+    #   does not define a primary key.
+    def primary_key_value
+      unless self.class.primary_key?
+        raise PrimaryKeyMissing, "#{self.class} does not define a primary key"
+      end
+
+      attributes[self.class.primary_key_name]
+    end
+    alias primary_key primary_key_value
+  end
+end

data/lib/stannum/entities/properties.rb

@@ -8,6 +8,9 @@ module Stannum::Entities
   # This module provides a base for accessing and mutating entity properties
   # such as attributes and associations.
   module Properties
+    MEMORY_ADDRESS_PATTERN = /0x([0-9a-f]+)/
+    private_constant :MEMORY_ADDRESS_PATTERN
+
     # @param properties [Hash] the properties used to initialize the entity.
     def initialize(**properties)
       set_properties(properties, force: true)
@@ -78,11 +81,22 @@ module Stannum::Entities
 
     # @return [String] a string representation of the entity and its properties.
     def inspect
-      mapped = inspectable_properties.reduce('') do |memo, (key, value)|
-        memo + " #{key}: #{value.inspect}"
-      end
+      inspect_with_options
+    end
+
+    # @param options [Hash] options for inspecting the entity.
+    #
+    # @option options memory_address [Boolean] if true, displays the memory
+    #   address of the object (as per Object#inspect). Defaults to false.
+    # @option options properties [Boolean] if true, displays the entity
+    #   properties. Defaults to true.
+    #
+    # @return [String] a string representation of the entity and its properties.
+    def inspect_with_options(**options)
+      address = options[:memory_address] ? ":#{memory_address}" : ''
+      mapped  = inspect_properties(**options)
 
-      "#<#{self.class.name}#{mapped}>"
+      "#<#{self.class.name}#{address}#{mapped}>"
     end
 
     # Collects the entity properties.
@@ -148,14 +162,14 @@ module Stannum::Entities
 
     def handle_invalid_properties(properties, as: 'property')
       properties.each_key do |key|
-        tools.assertions.assert_name(key, as: as, error_class: ArgumentError)
+        tools.assertions.assert_name(key, as:, error_class: ArgumentError)
       end
 
-      raise ArgumentError, invalid_properties_message(properties, as: as)
+      raise ArgumentError, invalid_properties_message(properties, as:)
     end
 
-    def inspectable_properties
-      {}
+    def inspect_properties(**)
+      ''
     end
 
     def invalid_properties_message(properties, as: 'property')
@@ -163,6 +177,14 @@ module Stannum::Entities
         properties.keys.map(&:inspect).join(', ')
     end
 
+    def memory_address
+      Object
+        .instance_method(:inspect)
+        .bind(self)
+        .call
+        .match(MEMORY_ADDRESS_PATTERN)[1]
+    end
+
     def set_property(key, _)
       raise ArgumentError, "unknown property #{key.inspect}"
     end

data/lib/stannum/entities.rb

@@ -7,7 +7,10 @@ require 'stannum/entities'
 module Stannum
   # Namespace for modules implementing Entity functionality.
   module Entities
-    autoload :Attributes, 'stannum/entities/attributes'
-    autoload :Properties, 'stannum/entities/properties'
+    autoload :Attributes,   'stannum/entities/attributes'
+    autoload :Associations, 'stannum/entities/associations'
+    autoload :Constraints,  'stannum/entities/constraints'
+    autoload :PrimaryKey,   'stannum/entities/primary_key'
+    autoload :Properties,   'stannum/entities/properties'
   end
 end

data/lib/stannum/entity.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
 require 'stannum'
+require 'stannum/entities/associations'
 require 'stannum/entities/attributes'
 require 'stannum/entities/constraints'
+require 'stannum/entities/primary_key'
 require 'stannum/entities/properties'
 
 module Stannum
@@ -78,6 +80,8 @@ module Stannum
   module Entity
     include Stannum::Entities::Properties
     include Stannum::Entities::Attributes
+    include Stannum::Entities::Associations
+    include Stannum::Entities::PrimaryKey
     include Stannum::Entities::Constraints
   end
 end

data/lib/stannum/errors.rb

@@ -326,7 +326,7 @@ module Stannum
     #     .add(:not_integer, message: 'is outside the range')
     #     .add(:not_in_range)
     def add(type, message: nil, **data)
-      error  = build_error(data: data, message: message, type: type)
+      error  = build_error(data:, message:, type:)
       hashed = error.hash
 
       return self if @cache.include?(hashed)
@@ -436,7 +436,7 @@ module Stannum
     # @overload each
     #   Iterates through the errors, yielding each error to the provided block.
     #
-    #   @yieldparam error [Hash<Symbol=>Object>] The error object. Each error
+    #   @yieldparam error [Hash{Symbol=>Object}] The error object. Each error
     #     is a hash containing the keys :data, :message, :path and :type.
     def each
       return to_enum(:each) { size } unless block_given?
@@ -592,14 +592,12 @@ module Stannum
 
     protected
 
-    def each_error(&block)
+    def each_error(&)
       return enum_for(:each_error) unless block_given?
 
-      @errors.each(&block)
+      @errors.each(&)
 
-      @children.each_value do |child|
-        child.each_error(&block)
-      end
+      @children.each_value { |child| child.each_error(&) }
     end
 
     def update_errors(other_errors)
@@ -621,10 +619,10 @@ module Stannum
       type = normalize_type(type)
       msg  = normalize_message(message)
 
-      { data: data, message: msg, type: type }
+      { data:, message: msg, type: }
     end
 
-    def compare_hashed_errors(other_errors)
+    def compare_hashed_errors(other_errors) # rubocop:disable Naming/PredicateMethod
       hashes       = Set.new(map(&:hash))
       other_hashes = Set.new(other_errors.map(&:hash))
 
@@ -669,7 +667,7 @@ module Stannum
       child = self.class.new
 
       ary.each do |item|
-        err  = normalize_array_item(item, allow_nil: allow_nil)
+        err  = normalize_array_item(item, allow_nil:)
         data = err.fetch(:data, {})
         path = err.fetch(:path, [])
 
@@ -708,9 +706,7 @@ module Stannum
 
       return value.dup if value.is_a?(self.class)
 
-      if value.is_a?(Array)
-        return normalize_array_value(value, allow_nil: allow_nil)
-      end
+      return normalize_array_value(value, allow_nil:) if value.is_a?(Array)
 
       raise ArgumentError, invalid_value_error(allow_nil)
     end

data/lib/stannum/messages/default_strategy.rb

@@ -18,7 +18,7 @@ module Stannum::Messages
       @load_paths ||= DEFAULT_LOAD_PATHS.dup
     end
 
-    # @param configuration [Hash{Symbol, Object}] The configured messages.
+    # @param configuration [Hash{Symbol=>Object}] The configured messages.
     # @param load_paths [Array<String>] The directories from which to load
     #   configured error messages.
     # @param locale [String] The locale used to load and scope configured
@@ -97,7 +97,7 @@ module Stannum::Messages
       Stannum::Messages::DefaultLoader
         .new(
           file_paths: load_paths,
-          locale:     locale
+          locale:
         )
         .call
     end

data/lib/stannum/parameter_validation.rb

@@ -126,11 +126,11 @@ module Stannum
         self::MethodValidations.define_method(method_name) \
         do |*arguments, **keywords, &block|
           result = match_parameters_to_contract(
-            arguments:   arguments,
-            block:       block,
-            contract:    contract,
-            keywords:    keywords,
-            method_name: method_name
+            arguments:,
+            block:,
+            contract:,
+            keywords:,
+            method_name:
           )
 
           return result unless result == VALIDATION_SUCCESS
@@ -199,17 +199,17 @@ module Stannum
     )
       match, errors = contract.match(
         {
-          arguments: arguments,
-          keywords:  keywords,
-          block:     block
+          arguments:,
+          keywords:,
+          block:
         }
       )
 
       return VALIDATION_SUCCESS if match
 
       handle_invalid_parameters(
-        errors:      errors,
-        method_name: method_name
+        errors:,
+        method_name:
       )
     end
   end

data/lib/stannum/rspec/match_errors_matcher.rb

@@ -27,7 +27,7 @@ module Stannum::RSpec
     end
 
     # Checks that the given errors do not match the expected errors.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       @actual = actual.is_a?(Stannum::Errors) ? actual.to_a : actual
 
       errors? && equality_matcher.does_not_match?(@actual)

data/lib/stannum/rspec/validate_parameter.rb

@@ -15,8 +15,8 @@ module Stannum::RSpec
     # @return [Stannum::RSpec::ValidateParameterMatcher] the matcher.
     def validate_parameter(method_name, parameter_name)
       Stannum::RSpec::ValidateParameterMatcher.new(
-        method_name:    method_name,
-        parameter_name: parameter_name
+        method_name:,
+        parameter_name:
       )
     end
   end

data/lib/stannum/rspec/validate_parameter_matcher.rb

@@ -18,13 +18,21 @@ module Stannum::RSpec
     class InvalidParameterHandledError < StandardError; end
     private_constant :InvalidParameterHandledError
 
+    EXTRA_PARAMETER_ERROR_TYPES = Set.new(
+      [
+        Stannum::Constraints::Parameters::ExtraArguments::TYPE,
+        Stannum::Constraints::Parameters::ExtraKeywords::TYPE
+      ]
+    ).freeze
+    private_constant :EXTRA_PARAMETER_ERROR_TYPES
+
     class << self
       # @private
       def add_parameter_mapping(map:, match:)
         raise ArgumentError, 'map must be a Proc'   unless map.is_a?(Proc)
         raise ArgumentError, 'match must be a Proc' unless match.is_a?(Proc)
 
-        parameter_mappings << { match: match, map: map }
+        parameter_mappings << { match:, map: }
       end
 
       # @private
@@ -33,12 +41,12 @@ module Stannum::RSpec
           match = keywords.fetch(:match)
           map   = keywords.fetch(:map)
 
-          next unless match.call(actual: actual, method_name: method_name)
+          next unless match.call(actual:, method_name:)
 
-          return map.call(actual: actual, method_name: method_name)
+          return map.call(actual:, method_name:)
         end
 
-        unwrapped_method(actual: actual, method_name: method_name).parameters
+        unwrapped_method(actual:, method_name:).parameters
       end
 
       private
@@ -109,7 +117,7 @@ module Stannum::RSpec
     #
     # @return [true, false] false if the object validates the parameter,
     #   otherwise true.
-    def does_not_match?(actual)
+    def does_not_match?(actual) # rubocop:disable Naming/PredicatePrefix
       disallow_fluent_options!
 
       @actual         = actual
@@ -313,14 +321,8 @@ module Stannum::RSpec
     end
 
     def extra_parameter?
-      extra_arguments_type =
-        Stannum::Constraints::Parameters::ExtraArguments::TYPE
-      extra_keywords_type =
-        Stannum::Constraints::Parameters::ExtraKeywords::TYPE
-
       return false unless scoped_errors(indexed: true).any? do |error|
-        error[:type] == extra_arguments_type ||
-        error[:type] == extra_keywords_type
+        EXTRA_PARAMETER_ERROR_TYPES.include?(error[:type])
       end
 
       @failure_reason = :parameter_not_validated
@@ -372,7 +374,7 @@ module Stannum::RSpec
 
     def method_parameters
       @method_parameters ||=
-        self.class.map_parameters(actual: actual, method_name: method_name)
+        self.class.map_parameters(actual:, method_name:)
     end
 
     def mock_validation_handler