mongoid 7.0.10 → 7.1.4

data/lib/mongoid/association.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 require 'mongoid/association/accessors'
 require 'mongoid/association/builders'
 require 'mongoid/association/bindable'
@@ -63,7 +66,7 @@ module Mongoid
       @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?
@@ -75,7 +78,7 @@ module Mongoid
       _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?
@@ -103,7 +106,7 @@ module Mongoid
       _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?
@@ -115,7 +118,7 @@ module Mongoid
       _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?
@@ -127,10 +130,10 @@ module Mongoid
       _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.

data/lib/mongoid/association/accessors.rb

@@ -1,55 +1,63 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
 
-    # This module contains all the behaviour related to accessing relations
+    # This module contains all the behavior related to accessing associations
     # through the getters and setters, and how to delegate to builders to
     # create new ones.
     module Accessors
       extend ActiveSupport::Concern
 
-      # Builds the related document and creates the relation unless the
-      # document is nil, then sets the relation on this document.
+      # Builds the related document and creates the association unless the
+      # document is nil, then sets the association on this document.
       #
-      # @example Build the relation.
+      # @example Build the association.
       #   person.__build__(:addresses, { :_id => 1 }, association)
       #
-      # @param [ String, Symbol ] name The name of the relation.
+      # @param [ String, Symbol ] name The name of the association.
       # @param [ Hash, BSON::ObjectId ] object The id or attributes to use.
       # @param [ Association ] association The association metadata.
+      # @param [ Hash ] selected_fields Fields which were retrieved via #only.
+      #   If selected_fields is specified, fields not listed in it will not be
+      #   accessible in the built document.
       #
-      # @return [ Proxy ] The relation.
+      # @return [ Proxy ] The association.
       #
       # @since 2.0.0.rc.1
-      def __build__(name, object, association)
-        relation = create_relation(object, association)
+      def __build__(name, object, association, selected_fields = nil)
+        relation = create_relation(object, association, selected_fields)
         set_relation(name, relation)
       end
 
-      # Create a relation from an object and association.
+      # Create an association from an object and association metadata.
       #
-      # @example Create the relation.
+      # @example Create the association.
       #   person.create_relation(document, association)
       #
-      # @param [ Document, Array<Document> ] object The relation target.
+      # @param [ Document, Array<Document> ] object The association target.
       # @param [ Association ] association The association metadata.
+      # @param [ Hash ] selected_fields Fields which were retrieved via #only.
+      #   If selected_fields is specified, fields not listed in it will not be
+      #   accessible in the created association document.
       #
-      # @return [ Proxy ] The relation.
+      # @return [ Proxy ] The association.
       #
       # @since 2.0.0.rc.1
-      def create_relation(object, association)
+      def create_relation(object, association, selected_fields = nil)
         type = @attributes[association.inverse_type]
-        target = association.build(self, object, type)
+        target = association.build(self, object, type, selected_fields)
         target ? association.create_relation(self, target) : nil
       end
 
-      # Resets the criteria inside the relation proxy. Used by many-to-many
-      # relations to keep the underlying ids array in sync.
+      # Resets the criteria inside the association proxy. Used by many-to-many
+      # associations to keep the underlying ids array in sync.
       #
-      # @example Reset the relation criteria.
+      # @example Reset the association criteria.
       #   person.reset_relation_criteria(:preferences)
       #
-      # @param [ Symbol ] name The name of the relation.
+      # @param [ Symbol ] name The name of the association.
       #
       # @since 3.0.14
       def reset_relation_criteria(name)
@@ -58,16 +66,16 @@ module Mongoid
         end
       end
 
-      # Set the supplied relation to an instance variable on the class with the
+      # Set the supplied association to an instance variable on the class with the
       # provided name. Used as a helper just for code cleanliness.
       #
       # @example Set the proxy on the document.
       #   person.set(:addresses, addresses)
       #
-      # @param [ String, Symbol ] name The name of the relation.
-      # @param [ Proxy ] relation The relation to set.
+      # @param [ String, Symbol ] name The name of the association.
+      # @param [ Proxy ] relation The association to set.
       #
-      # @return [ Proxy ] The relation.
+      # @return [ Proxy ] The association.
       #
       # @since 2.0.0.rc.1
       def set_relation(name, relation)
@@ -76,20 +84,20 @@ module Mongoid
 
       private
 
-      # Get the relation. Extracted out from the getter method to avoid
+      # Get the association. Extracted out from the getter method to avoid
       # infinite recursion when overriding the getter.
       #
       # @api private
       #
-      # @example Get the relation.
+      # @example Get the association.
       #   document.get_relation(:name, association)
       #
-      # @param [ Symbol ] name The name of the relation.
+      # @param [ Symbol ] name The name of the association.
       # @param [ Association ] association The association metadata.
-      # @param [ Object ] object The object used to build the relation.
-      # @param [ true, false ] reload If the relation is to be reloaded.
+      # @param [ Object ] object The object used to build the association.
+      # @param [ true, false ] reload If the association is to be reloaded.
       #
-      # @return [ Proxy ] The relation.
+      # @return [ Proxy ] The association.
       #
       # @since 3.0.16
       def get_relation(name, association, object, reload = false)
@@ -101,13 +109,83 @@ module Mongoid
               if object && needs_no_database_query?(object, association)
                 __build__(name, object, association)
               else
-                __build__(name, attributes[association.key], association)
+                selected_fields = _mongoid_filter_selected_fields(association.key)
+                __build__(name, attributes[association.key], association, selected_fields)
               end
             end
           end
         end
       end
 
+      # Returns a subset of __selected_fields attribute applicable to the
+      # (embedded) association with the given key, or nil if no projection
+      # is to be performed.
+      #
+      # For example, if __selected_fields is {'a' => 1, 'b.c' => 2, 'b.c.f' => 3},
+      # and assoc_key is 'b', return value would be {'c' => 2, 'c.f' => 3}.
+      #
+      # @param [ String ] assoc_key
+      #
+      # @return [ Hash | nil ]
+      #
+      # @api private
+      def _mongoid_filter_selected_fields(assoc_key)
+        return nil unless __selected_fields
+
+        projecting_assoc = false
+
+        filtered = {}
+        __selected_fields.each do |k, v|
+          bits = k.split('.')
+
+          # If we are asked to project an association, we need all of that
+          # association's fields. However, we may be asked to project
+          # an association *and* its fields in the same query. In this case
+          # behavior differs according to server version:
+          #
+          # 4.2 and lower take the most recent projection specification, meaning
+          # projecting foo followed by foo.bar effectively projects foo.bar and
+          # projecting foo.bar followed by foo effectively projects foo.
+          # To match this behavior we need to track when we are being asked
+          # to project the association and when we are asked to project a field,
+          # and if we are asked to project the association last we need to
+          # remove any field projections.
+          #
+          # 4.4 (and presumably higher) do not allow projection to be on an
+          # association and its field, so it doesn't matter what we do. Hence
+          # we just need to handle the 4.2 and lower case correctly.
+          if bits.first == assoc_key
+            # Projecting the entire association OR some of its fields
+            if bits.length > 1
+              # Projecting a field
+              bits.shift
+              filtered[bits.join('.')] = v
+              projecting_assoc = false
+            else
+              # Projecting the entire association
+              projecting_assoc = true
+            end
+          end
+        end
+
+        if projecting_assoc
+          # The last projection was of the entire association; we may have
+          # also been projecting fields, but discard the field projections
+          # and return nil indicating we want the entire association.
+          return nil
+        end
+
+        # Positional projection is specified as "foo.$". In this case the
+        # document that the $ is referring to should be retrieved with all
+        # fields. See https://docs.mongodb.com/manual/reference/operator/projection/positional/
+        # and https://jira.mongodb.org/browse/MONGOID-4769.
+        if filtered.keys == %w($)
+          filtered = nil
+        end
+
+        filtered
+      end
+
       def needs_no_database_query?(object, association)
         object.is_a?(Document) && !object.embedded? &&
             object._id == attributes[association.key]
@@ -157,12 +235,12 @@ module Mongoid
         [args.first || {}, args.size > 1 ? args[1] : {}]
       end
 
-      # Adds the existence check for relations.
+      # Adds the existence check for associations.
       #
       # @example Add the existence check.
       #   Person.define_existence_check!(association)
       #
-      # @example Check if a relation exists.
+      # @example Check if an association exists.
       #   person = Person.new
       #   person.has_game?
       #   person.game?
@@ -184,14 +262,14 @@ module Mongoid
         end
       end
 
-      # Defines the getter for the relation. Nothing too special here: just
-      # return the instance variable for the relation if it exists or build
+      # Defines the getter for the association. Nothing too special here: just
+      # return the instance variable for the association if it exists or build
       # the thing.
       #
-      # @example Set up the getter for the relation.
+      # @example Set up the getter for the association.
       #   Person.define_getter!(association)
       #
-      # @param [ Association ] association The association metadata for the relation.
+      # @param [ Association ] association The association metadata for the association.
       #
       # @return [ Class ] The class being set up.
       #
@@ -209,13 +287,13 @@ module Mongoid
         end
       end
 
-      # Defines the getter for the ids of documents in the relation. Should
-      # be specify only for referenced many relations.
+      # Defines the getter for the ids of documents in the association. Should
+      # be specify only for referenced many associations.
       #
-      # @example Set up the ids getter for the relation.
+      # @example Set up the ids getter for the association.
       #   Person.define_ids_getter!(association)
       #
-      # @param [ Association ] association The association metadata for the relation.
+      # @param [ Association ] association The association metadata for the association.
       #
       # @return [ Class ] The class being set up.
       def self.define_ids_getter!(association)
@@ -227,15 +305,15 @@ module Mongoid
         end
       end
 
-      # Defines the setter for the relation. This does a few things based on
+      # Defines the setter for the association. This does a few things based on
       # some conditions. If there is an existing association, a target
-      # substitution will take place, otherwise a new relation will be
+      # substitution will take place, otherwise a new association will be
       # created with the supplied target.
       #
-      # @example Set up the setter for the relation.
+      # @example Set up the setter for the association.
       #   Person.define_setter!(association)
       #
-      # @param [ Association ] association The association metadata for the relation.
+      # @param [ Association ] association The association metadata for the association.
       #
       # @return [ Class ] The class being set up.
       #
@@ -261,15 +339,15 @@ module Mongoid
       end
 
       # Defines the setter method that allows you to set documents
-      # in this relation by their ids. The defined setter, finds
-      # documents with given ids and invokes regular relation setter
+      # in this association by their ids. The defined setter, finds
+      # documents with given ids and invokes regular association setter
       # with found documents. Ids setters should be defined only for
-      # referenced many relations.
+      # referenced many associations.
       #
-      # @example Set up the id_setter for the relation.
+      # @example Set up the id_setter for the association.
       #   Person.define_ids_setter!(association)
       #
-      #  @param [ Association ] association The association for the relation.
+      #  @param [ Association ] association The association for the association.
       #
       #  @return [ Class ] The class being set up.
       def self.define_ids_setter!(association)
@@ -281,13 +359,13 @@ module Mongoid
         end
       end
 
-      # Defines a builder method for an embeds_one relation. This is
+      # Defines a builder method for an embeds_one association. This is
       # defined as #build_name.
       #
       # @example
       #   Person.define_builder!(association)
       #
-      # @param [ Association ] association The association for the relation.
+      # @param [ Association ] association The association for the association.
       #
       # @return [ Class ] The class being set up.
       #
@@ -307,14 +385,14 @@ module Mongoid
         end
       end
 
-      # Defines a creator method for an embeds_one relation. This is
+      # Defines a creator method for an embeds_one association. This is
       # defined as #create_name. After the object is built it will
       # immediately save.
       #
       # @example
       #   Person.define_creator!(association)
       #
-      # @param [ Association ] association The association for the relation.
+      # @param [ Association ] association The association for the association.
       #
       # @return [ Class ] The class being set up.
       #

data/lib/mongoid/association/bindable.rb

@@ -1,8 +1,10 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
 
-    # Superclass for all objects that bind relations together.
+    # Superclass for all objects that bind associations together.
     module Bindable
       include Threaded::Lifecycle
 
@@ -84,7 +86,7 @@ module Mongoid
       end
 
       # Set the type of the related document on the foreign type field, used
-      # when relations are polymorphic.
+      # when associations are polymorphic.
       #
       # @api private
       #
@@ -102,7 +104,7 @@ module Mongoid
       end
 
       # Set the type of the related document on the foreign type field, used
-      # when relations are polymorphic.
+      # when associations are polymorphic.
       #
       # @api private
       #
@@ -137,7 +139,7 @@ module Mongoid
         end
       end
 
-      # Bind the provided document with the base from the parent relation.
+      # Bind the provided document with the base from the parent association.
       #
       # @api private
       #
@@ -177,7 +179,7 @@ module Mongoid
         end
       end
 
-      # Bind the provided document with the base from the parent relation.
+      # Bind the provided document with the base from the parent association.
       #
       # @api private
       #

data/lib/mongoid/association/builders.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # encoding: utf-8
 
 module Mongoid
   module Association
 
     # This module is responsible for defining the build and create methods used
-    # in one to one relations.
+    # in one to one associations.
     #
     # @example Methods that get created.
     #
@@ -43,7 +44,7 @@ module Mongoid
       # @example
       #   Person.define_builder!(association)
       #
-      # @param [ Association ] association The association metadata for the relation.
+      # @param [ Association ] association The association metadata for the association.
       #
       # @return [ Class ] The class being set up.
       #
@@ -68,7 +69,7 @@ module Mongoid
       # @example
       #   Person.define_creator!(association)
       #
-      # @param [ Association ] association The association metadata for the relation.
+      # @param [ Association ] association The association metadata for the association.
       #
       # @return [ Class ] The class being set up.
       #