mongoid 7.0.12 → 7.3.3

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,95 @@ 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.
+      #
+      # Also returns nil if exclusionary projection was requested but it does
+      # not exclude the field of the association.
+      #
+      # 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
+
+        # If the list of fields was specified using #without instead of #only
+        # and the provided list does not include the association, any of its
+        # fields should be allowed.
+        if __selected_fields.values.all? { |v| v == 0 } &&
+          __selected_fields.keys.none? { |k| k.split('.', 2).first == assoc_key }
+        then
+          return nil
+        end
+
+        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 +247,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 +274,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,33 +299,33 @@ 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)
         ids_method = "#{association.name.to_s.singularize}_ids"
         association.inverse_class.tap do |klass|
           klass.re_define_method(ids_method) do
-            send(association.name).only(:id).map(&:id)
+            send(association.name).only(:_id).map(&:_id)
           end
         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 +351,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 +371,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 +397,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.
       #

data/lib/mongoid/association/constrainable.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
 
@@ -8,7 +10,7 @@ module Mongoid
     module Constrainable
 
       # Convert the supplied object to the appropriate type to set as the
-      # foreign key for a relation.
+      # foreign key for an association.
       #
       # @example Convert the object.
       #   constraint.convert("12345")
@@ -31,10 +33,10 @@ module Mongoid
       end
 
       private
-      
+
       def convert_polymorphic(object)
         if object.is_a?(Mongoid::Document)
-          object.id
+          object._id
         else
           BSON::ObjectId.mongoize(object)
         end

data/lib/mongoid/association/depending.rb

@@ -1,8 +1,11 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 module Mongoid
   module Association
 
-    # This module defines the behaviour for setting up cascading deletes and
-    # nullifies for relations, and how to delegate to the appropriate strategy.
+    # This module defines the behavior for setting up cascading deletes and
+    # nullifies for associations, and how to delegate to the appropriate strategy.
     module Depending
       extend ActiveSupport::Concern
 
@@ -38,11 +41,6 @@ module Mongoid
           :restrict_with_error
       ]
 
-      # The error message when a strategy cannot delete objects because there are associated objects.
-      #
-      # @since 7.0
-      RESTRICT_ERROR_MSG = 'Cannot delete record because associated objects exist.'.freeze
-
       # Attempt to add the cascading information for the document to know how
       # to handle associated documents on a removal.
       #
@@ -80,13 +78,13 @@ module Mongoid
       # the appropriate strategy to perform the operation.
       #
       # @example Execute cascades.
-      #   document.apply_delete_dependencies!
+      #   document.apply_destroy_dependencies!
       #
       # @since 2.0.0.rc.1
-      def apply_delete_dependencies!
+      def apply_destroy_dependencies!
         self.class._all_dependents.each do |association|
-          if association.try(:dependent)
-            send("_dependent_#{association.dependent}!", association)
+          if dependent = association.try(:dependent)
+            send("_dependent_#{dependent}!", association)
           end
         end
       end
@@ -128,7 +126,7 @@ module Mongoid
 
       def _dependent_restrict_with_error!(association)
         if (relation = send(association.name)) && !relation.blank?
-          errors.add(association.name, RESTRICT_ERROR_MSG)
+          errors.add(association.name, :destroy_restrict_with_error_dependencies_exist)
           throw(:abort, false)
         end
       end

data/lib/mongoid/association/eager_loadable.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 require "mongoid/association/referenced/eager"
 
 module Mongoid

data/lib/mongoid/association/embedded/batchable.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Embedded
 
-      # Contains behaviour for executing operations in batch on embedded
+      # Contains behavior for executing operations in batch on embedded
       # documents.
       module Batchable
         include Positional
@@ -24,7 +26,7 @@ module Mongoid
           execute_batch_push(docs)
         end
 
-        # Clear all of the docs out of the relation in a single swipe.
+        # Clear all of the docs out of the association in a single swipe.
         #
         # @example Clear all docs.
         #   batchable.batch_clear(docs)
@@ -327,7 +329,7 @@ module Mongoid
             self.path = doc.atomic_path unless path
             execute_callback :before_remove, doc
             unless _assigning?
-              doc.apply_delete_dependencies!
+              doc.apply_destroy_dependencies!
               doc.run_before_callbacks(:destroy) if method == :destroy
             end
             _target.delete_one(doc)

data/lib/mongoid/association/embedded/cyclic.rb

@@ -1,10 +1,12 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Embedded
 
       # This module provides convenience macros for using cyclic embedded
-      # relations.
+      # associations.
       module Cyclic
         extend ActiveSupport::Concern
 
@@ -14,7 +16,7 @@ module Mongoid
 
         module ClassMethods
 
-          # Create a cyclic embedded relation that creates a tree hierarchy for
+          # Create a cyclic embedded association that creates a tree hierarchy for
           # the document and many embedded child documents.
           #
           # @example Set up a recursive embeds many.
@@ -44,7 +46,7 @@ module Mongoid
             embedded_in cyclic_parent_name, class_name: self.name, cyclic: true
           end
 
-          # Create a cyclic embedded relation that creates a single self
+          # Create a cyclic embedded association that creates a single self
           # referencing relationship for a parent and a single child.
           #
           # @example Set up a recursive embeds one.
@@ -85,7 +87,7 @@ module Mongoid
           #
           # @since 2.0.0.rc.1
           def cyclic_parent_name
-            ("parent_" << self.name.demodulize.underscore.singularize).to_sym
+            ("parent_#{self.name.demodulize.underscore.singularize}").to_sym
           end
 
           # Determines the child name given the class.
@@ -93,14 +95,14 @@ module Mongoid
           # @example Determine the child name.
           #   Role.cyclic_child_name
           #
-          # @param [ true, false ] many Is the a many relation?
+          # @param [ true, false ] many Is the a many association?
           #
           # @return [ String ] "child_" plus the class name underscored in
           #   singular or plural form.
           #
           # @since 2.0.0.rc.1
           def cyclic_child_name(many = true)
-            ("child_" << self.name.demodulize.underscore.send(many ? :pluralize : :singularize)).to_sym
+            ("child_#{self.name.demodulize.underscore.send(many ? :pluralize : :singularize)}").to_sym
           end
         end
       end

data/lib/mongoid/association/embedded/embedded_in/binding.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 module Mongoid
   module Association
     module Embedded
@@ -9,7 +12,7 @@ module Mongoid
         class Binding
           include Bindable
 
-          # Binds the base object to the inverse of the relation. This is so we
+          # Binds the base object to the inverse of the association. This is so we
           # are referenced to the actual objects themselves on both sides.
           #
           # This case sets the association metadata on the inverse object as well as the

data/lib/mongoid/association/embedded/embedded_in/buildable.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 module Mongoid
   module Association
     module Embedded
@@ -18,12 +21,15 @@ module Mongoid
           # @param [ Object ] base The object.
           # @param [ Object ] object The parent hash or document.
           # @param [ String ] type Not used in this context.
+          # @param [ Hash ] selected_fields Fields which were retrieved via
+          #   #only. If selected_fields are specified, fields not listed in it
+          #   will not be accessible in the built document.
           #
           # @return [ Document ] A single document.
-          def build(base, object, type = nil)
+          def build(base, object, type = nil, selected_fields = nil)
             return object unless object.is_a?(Hash)
             if _loading?
-              Factory.from_db(klass, object)
+              Factory.from_db(klass, object, nil, selected_fields)
             else
               Factory.build(klass, object)
             end