mongoid 7.0.2 → 8.1.1

data/lib/mongoid/association/relatable.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'mongoid/association/constrainable'
 require 'mongoid/association/options'
 
@@ -5,8 +7,6 @@ module Mongoid
   module Association
 
     # This module provides behaviors shared between Association types.
-    #
-    # @since 7.0
     module Relatable
       include Constrainable
       include Options
@@ -14,8 +14,6 @@ module Mongoid
       # The options shared between all association types.
       #
       # @return [ Array<Symbol> ] The shared options.
-      #
-      # @since 7.0
       SHARED_OPTIONS = [
                          :class_name,
                          :inverse_of,
@@ -26,32 +24,24 @@ module Mongoid
       # The primary key default.
       #
       # @return [ String ] The primary key field default.
-      #
-      # @since 7.0
       PRIMARY_KEY_DEFAULT = '_id'.freeze
 
       # The name of the association.
       #
-      # @return [ Symbol ] The name of the relation.
-      #
-      # @since 7.0
+      # @return [ Symbol ] The name of the association.
       attr_reader :name
 
       # The options on this association.
       #
       # @return [ Hash ] The options.
-      #
-      # @since 7.0
       attr_reader :options
 
       # Initialize the Association.
       #
-      # @param [ Class ] _class The class of the model who owns this relation.
+      # @param [ Class ] _class The class of the model who owns this association.
       # @param [ Symbol ] name The name of the association.
-      # @param [ Hash ] opts The relation options.
+      # @param [ Hash ] opts The association options.
       # @param [ Block ] block The optional block.
-      #
-      # @since 7.0
       def initialize(_class, name, opts = {}, &block)
         @owner_class = _class
         @name = name
@@ -68,8 +58,6 @@ module Mongoid
       # Compare this association to another.
       #
       # @return [ Object ] The object to compare to this association.
-      #
-      # @since 7.0
       def ==(other)
         relation_class_name == other.relation_class_name &&
           inverse_class_name == other.inverse_class_name &&
@@ -81,20 +69,16 @@ module Mongoid
       #
       # @param [ Symbol ] callback_type The type of callback type.
       #
-      # @return [ Array<Proc, Symbol> ] A list of the callbacks, either method
+      # @return [ Array<Proc | Symbol> ] A list of the callbacks, either method
       #   names or Procs.
-      #
-      # @since 7.0
       def get_callbacks(callback_type)
         Array(options[callback_type])
       end
 
       # Get the type setter.
-      # @note Only relevant for polymorphic relations that take the :as option.
+      # @note Only relevant for polymorphic associations that take the :as option.
       #
       # @return [ String ] The type setter method.
-      #
-      # @since 7.0
       def type_setter
         @type_setter ||= type.__setter__
       end
@@ -104,9 +88,7 @@ module Mongoid
       #
       # @param [ Document ] doc The document to be bound.
       #
-      # @return [ true, false ] Whether the document can be bound.
-      #
-      # @since 7.0
+      # @return [ true | false ] Whether the document can be bound.
       def bindable?(doc); false; end
 
       # Get the inverse names.
@@ -115,10 +97,10 @@ module Mongoid
       #   determining inverses.
       #
       # @return [ Array<Symbol> ] The list of inverse names.
-      #
-      # @since 7.0
       def inverses(other = nil)
         return [ inverse_of ] if inverse_of
+        return [] if @options.key?(:inverse_of) && !inverse_of
+
         if polymorphic?
           polymorphic_inverses(other)
         else
@@ -132,8 +114,6 @@ module Mongoid
       #   determining inverses.
       #
       # @return [ Association ] The inverse's association metadata.
-      #
-      # @since 7.0
       def inverse_association(other = nil)
         (other || relation_class).relations[inverse(other)]
       end
@@ -141,55 +121,75 @@ module Mongoid
       # Get the inverse type.
       #
       # @return [ nil ] Default is nil for an association.
-      #
-      # @since 7.0
       def inverse_type; end
 
-      # The class name of the relation object(s).
+      # The class name, possibly unqualified or :: prefixed, of the association
+      # object(s).
+      #
+      # This method returns the class name as it is used in the association
+      # definition. If :class_name option is given in the association, the
+      # exact value of that option is returned here. If :class_name option is
+      # not given, the name of the class is calculated from association name
+      # but is not resolved to the actual class.
       #
-      # @return [ String ] The relation objects' class name.
+      # The class name returned by this method may not correspond to a defined
+      # class, either because the corresponding class has not been loaded yet,
+      # or because the association references a non-existent class altogether.
+      # To obtain the association class, use +relation_class+ method.
       #
-      # @since 7.0
+      # @note The return value of this method should not be used to determine
+      #   whether two associations have the same target class, because the
+      #   return value is not always a fully qualified class name. To compare
+      #   classes, retrieve the class instance of the association target using
+      #   the +relation_class+ method.
+      #
+      # @return [ String ] The association objects' class name.
       def relation_class_name
-        @class_name ||= @options[:class_name] || ActiveSupport::Inflector.classify(name_with_module)
+        @class_name ||= @options[:class_name] || ActiveSupport::Inflector.classify(name)
       end
       alias :class_name :relation_class_name
 
-      # The class of the relation object(s).
+      # The class of the association object(s).
+      #
+      # This method returns the class instance corresponding to
+      # +relation_class_name+, resolved relative to the host document class.
       #
-      # @return [ String ] The relation objects' class.
+      # If the class does not exist, this method raises NameError. This can
+      # happen because the target class has not yet been defined. Note that
+      # polymorphic associations generally do not have a well defined target
+      # class because the target class can change from one object to another,
+      # and calling this method on a polymorphic association will generally
+      # fail with a NameError or produce misleading results (if a class does
+      # happen to be defined with the same name as the association name).
       #
-      # @since 7.0
-      def klass
-        @klass ||= relation_class_name.constantize
+      # @return [ String ] The association objects' class.
+      def relation_class
+        @klass ||= begin
+          cls_name = @options[:class_name] || ActiveSupport::Inflector.classify(name)
+          resolve_name(inverse_class, cls_name)
+        end
       end
-      alias :relation_class :klass
+      alias :klass :relation_class
 
-      # The class name of the object owning this relation.
+      # The class name of the object owning this association.
       #
       # @return [ String ] The owning objects' class name.
-      #
-      # @since 7.0
       def inverse_class_name
         @inverse_class_name ||= @owner_class.name
       end
 
-      # The class of the object owning this relation.
+      # The class of the object owning this association.
       #
       # @return [ String ] The owning objects' class.
-      #
-      # @since 7.0
       def inverse_class
         @owner_class
       end
       alias :inverse_klass :inverse_class
 
-      # The foreign key field if this relation stores a foreign key.
+      # The foreign key field if this association stores a foreign key.
       # Otherwise, the primary key.
       #
-      # @return [ Symbol, String ] The primary key.
-      #
-      # @since 7.0
+      # @return [ Symbol | String ] The primary key.
       def key
         stores_foreign_key? ? foreign_key : primary_key
       end
@@ -197,8 +197,6 @@ module Mongoid
       # The name of the setter on this object for assigning an associated object.
       #
       # @return [ String ] The setter name.
-      #
-      # @since 7.0
       def setter
         @setter ||= "#{name}="
       end
@@ -206,8 +204,6 @@ module Mongoid
       # The name of the inverse setter method.
       #
       # @return [ String ] The name of the inverse setter.
-      #
-      # @since 7.0
       def inverse_setter(other = nil)
         @inverse_setter ||= "#{inverses(other).first}=" unless inverses(other).blank?
       end
@@ -215,32 +211,26 @@ module Mongoid
       # The name of the foreign key setter method.
       #
       # @return [ String ] The name of the foreign key setter.
-      #
-      # @since 7.0
       def foreign_key_setter
         # note: You can't check if this association stores foreign key
         # See HasOne and HasMany binding, they referenced foreign_key_setter
         @foreign_key_setter ||= "#{foreign_key}=" if foreign_key
       end
 
-      # The atomic path for this relation.
+      # The atomic path for this association.
       #
       # @return [  Mongoid::Atomic::Paths::Root ] The atomic path object.
-      #
-      # @since 7.0
       def path(document)
         relation.path(document)
       end
 
       # Gets the setter for the field that sets the type of document on a
-      # polymorphic relation.
+      # polymorphic association.
       #
       # @example Get the inverse type setter.
       #   association.inverse_type_setter
       #
       # @return [ String ] The name of the setter.
-      #
-      # @since 7.0
       def inverse_type_setter
         @inverse_type_setter ||= inverse_type.__setter__
       end
@@ -251,30 +241,24 @@ module Mongoid
       #   association.foreign_key_check
       #
       # @return [ String ] The foreign key check.
-      #
-      # @since 7.0
       def foreign_key_check
-        @foreign_key_check ||= "#{foreign_key}_changed?" if (stores_foreign_key? && foreign_key)
+        @foreign_key_check ||= "#{foreign_key}_previously_changed?" if (stores_foreign_key? && foreign_key)
       end
 
-      # Create a relation proxy object using the owner and target.
+      # Create an association proxy object using the owner and target.
       #
-      # @param [ Document ] owner The document this relation hangs off of.
-      # @param [ Document, Array<Document> ] target The target (parent) of the
-      #   relation.
+      # @param [ Document ] owner The document this association hangs off of.
+      # @param [ Document | Array<Document> ] target The target (parent) of the
+      #   association.
       #
       # @return [ Proxy ]
-      #
-      # @since 7.0
       def create_relation(owner, target)
         relation.new(owner, target, self)
       end
 
       # Whether the dependent method is destructive.
       #
-      # @return [ true, false ] If the dependent method is destructive.
-      #
-      # @since 7.0
+      # @return [ true | false ] If the dependent method is destructive.
       def destructive?
         @destructive ||= !!(dependent && (dependent == :delete_all || dependent == :destroy))
       end
@@ -282,8 +266,6 @@ module Mongoid
       # Get the counter cache column name.
       #
       # @return [ String ] The counter cache column name.
-      #
-      # @since 7.0
       def counter_cache_column_name
         @counter_cache_column_name ||= (@options[:counter_cache].is_a?(String) ||
             @options[:counter_cache].is_a?(Symbol)) ?
@@ -293,8 +275,6 @@ module Mongoid
       # Get the extension.
       #
       # @return [ Module ] The extension module, if one has been defined.
-      #
-      # @since 7.0
       def extension
         @extension ||= @options[:extend]
       end
@@ -302,8 +282,6 @@ module Mongoid
       # Get the inverse name.
       #
       # @return [ Symbol ] The inverse name.
-      #
-      # @since 7.0
       def inverse(other = nil)
         candidates = inverses(other)
         candidates.detect { |c| c } if candidates
@@ -311,10 +289,8 @@ module Mongoid
 
       # Whether the associated object(s) should be validated.
       #
-      # @return [ true, false ] If the associated object(s)
+      # @return [ true | false ] If the associated object(s)
       #   should be validated.
-      #
-      # @since 7.0
       def validate?
         @validate ||= if @options[:validate].nil?
                         validation_default
@@ -323,14 +299,39 @@ module Mongoid
                       end
       end
 
-      private
+      # @return [ Array<String> ] The associations above this one in the inclusion tree.
+      attr_accessor :parent_inclusions
 
-      def name_with_module
-        @module_path + name.to_s.capitalize
+      def parent_inclusions
+        @parent_inclusions ||= []
       end
 
+      # Is this association an embeds_many or has_many association?
+      #
+      # @return [ true | false ] true if it is a *_many association, false if not.
+      def many?
+        [Referenced::HasMany, Embedded::EmbedsMany].any? { |a| self.is_a?(a) }
+      end
+
+      # Is this association an embeds_one or has_one association?
+      #
+      # @return [ true | false ] true if it is a *_one association, false if not.
+      def one?
+        [Referenced::HasOne, Embedded::EmbedsOne].any? { |a| self.is_a?(a) }
+      end
+
+      # Is this association an embedded_in or belongs_to association?
+      #
+      # @return [ true | false ] true if it is an embedded_in or belongs_to
+      #   association, false if not.
+      def in_to?
+        [Referenced::BelongsTo, Embedded::EmbeddedIn].any? { |a| self.is_a?(a) }
+      end
+
+      private
+
       # Gets the model classes with inverse associations of this model. This is used to determine
-      # the classes on the other end of polymorphic relations with models.
+      # the classes on the other end of polymorphic associations with models.
       def inverse_association_classes
         Mongoid::Config.models.map { |m| inverse_association(m) }.compact.map(&:inverse_class)
       end
@@ -424,6 +425,65 @@ module Mongoid
       def default_inverse
         @default_inverse ||= klass.relations[inverse_klass.name.underscore]
       end
+
+      # Returns an array of classes/modules forming the namespace hierarchy
+      # where symbols referenced in the provided class/module would be looked
+      # up by Ruby. For example, if mod is Foo::Bar, this method would return
+      # [Foo::Bar, Foo, Object].
+      def namespace_hierarchy(mod)
+        parent = Object
+        hier = [parent]
+
+        # name is not present on anonymous modules
+        if mod.name
+          mod.name.split('::').each do |part|
+            parent = parent.const_get(part)
+            hier << parent
+          end
+        end
+
+        hier.reverse
+      end
+
+      # Resolves the given class/module name in the context of the specified
+      # module, as Ruby would when a constant is referenced in the source.
+      #
+      # @note This method can swallow exceptions produced during class loading,
+      #   because it rescues NameError internally. Since this method attempts
+      #   to load classes, failure during the loading process may also lead to
+      #   there being incomplete class definitions.
+      def resolve_name(mod, name)
+        cls = exc = nil
+        parts = name.to_s.split('::')
+        if parts.first == ''
+          parts.shift
+          hierarchy = [Object]
+        else
+          hierarchy = namespace_hierarchy(mod)
+        end
+        hierarchy.each do |ns|
+          begin
+            parts.each do |part|
+              # Simple const_get sometimes pulls names out of weird scopes,
+              # perhaps confusing the receiver (ns in this case) with the
+              # local scope. Walk the class hierarchy ourselves one node
+              # at a time by specifying false as the second argument.
+              ns = ns.const_get(part, false)
+            end
+            cls = ns
+            break
+          rescue NameError => e
+            if exc.nil?
+              exc = e
+            end
+          end
+        end
+        if cls.nil?
+          # Raise the first exception, this is from the most specific namespace
+          raise exc
+        end
+        cls
+      end
     end
   end
 end

data/lib/mongoid/association.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'mongoid/association/accessors'
 require 'mongoid/association/builders'
 require 'mongoid/association/bindable'
@@ -31,8 +33,6 @@ module Mongoid
     # Map the macros to their corresponding Association classes.
     #
     # @return [ Hash ] The mapping from macros to their Association class.
-    #
-    # @since 7.0
     MACRO_MAPPING = {
         embeds_one: Association::Embedded::EmbedsOne,
         embeds_many: Association::Embedded::EmbedsMany,
@@ -56,33 +56,27 @@ module Mongoid
     # @example Is the document embedded?
     #   address.embedded?
     #
-    # @return [ true, false ] True if the document has a parent document.
-    #
-    # @since 2.0.0.rc.1
+    # @return [ true | false ] True if the document has a parent document.
     def embedded?
       @embedded ||= (cyclic ? _parent.present? : self.class.embedded?)
     end
 
-    # Determine if the document is part of an embeds_many relation.
+    # Determine if the document is part of an embeds_many association.
     #
     # @example Is the document in an embeds many?
     #   address.embedded_many?
     #
-    # @return [ true, false ] True if in an embeds many.
-    #
-    # @since 2.0.0.rc.1
+    # @return [ true | false ] True if in an embeds many.
     def embedded_many?
       _association && _association.is_a?(Association::Embedded::EmbedsMany)
     end
 
-    # Determine if the document is part of an embeds_one relation.
+    # Determine if the document is part of an embeds_one association.
     #
     # @example Is the document in an embeds one?
     #   address.embedded_one?
     #
-    # @return [ true, false ] True if in an embeds one.
-    #
-    # @since 2.0.0.rc.1
+    # @return [ true | false ] True if in an embeds one.
     def embedded_one?
       _association && _association.is_a?(Association::Embedded::EmbedsOne)
     end
@@ -96,46 +90,38 @@ module Mongoid
     # @raise [ Errors::NoMetadata ] If no association metadata is present.
     #
     # @return [ Symbol ] The association name.
-    #
-    # @since 3.0.0
     def association_name
       raise Errors::NoMetadata.new(self.class.name) unless _association
       _association.name
     end
 
-    # Determine if the document is part of an references_many relation.
+    # Determine if the document is part of an references_many association.
     #
     # @example Is the document in a references many?
     #   post.referenced_many?
     #
-    # @return [ true, false ] True if in a references many.
-    #
-    # @since 2.0.0.rc.1
+    # @return [ true | false ] True if in a references many.
     def referenced_many?
       _association && _association.is_a?(Association::Referenced::HasMany)
     end
 
-    # Determine if the document is part of an references_one relation.
+    # Determine if the document is part of an references_one association.
     #
     # @example Is the document in a references one?
     #   address.referenced_one?
     #
-    # @return [ true, false ] True if in a references one.
-    #
-    # @since 2.0.0.rc.1
+    # @return [ true | false ] True if in a references one.
     def referenced_one?
       _association && _association.is_a?(Association::Referenced::HasOne)
     end
 
-    # Convenience method for iterating through the loaded relations and
+    # Convenience method for iterating through the loaded associations and
     # reloading them.
     #
-    # @example Reload the relations.
+    # @example Reload the associations.
     #   document.reload_relations
     #
     # @return [ Hash ] The association metadata.
-    #
-    # @since 2.1.6
     def reload_relations
       relations.each_pair do |name, meta|
         if instance_variable_defined?("@_#{name}")