mongoid 9.0.11 → 9.1.1

data/lib/mongoid/association/builders.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Association
-
     # This module is responsible for defining the build and create methods used
     # in one to one associations.
     #
@@ -22,17 +20,20 @@ module Mongoid
 
       private
 
-      # Parse out the attributes and the options from the args passed to a
-      # build_ or create_ methods.
-      #
-      # @example Parse the args.
-      #   doc.parse_args(:name => "Joe")
+      # Parses the arguments passed to the build and create methods. The first
+      # argument is always the attributes (defaulting to {} if not given). The
+      # last argument is always the options hash, if the last argument is a
+      # hash. The first of any remaining arguments is the type.
       #
-      # @param [ Hash... ] *args The arguments.
+      # @param [ Array ] args The arguments passed to the method.
       #
-      # @return [ Array<Hash> ] The attributes and options.
-      def parse_args(*args)
-        [ args.first || {}, args.size > 1 ? args[1] : {} ]
+      # @return [ Array ] An array containing the attributes, type, and options.
+      def parse_args(args)
+        attributes = args.shift || {}
+        opts = args.last.is_a?(Hash) ? args.pop : {}
+        type = args.shift
+
+        [ attributes, type, opts ]
       end
 
       # Defines a builder method. This is defined as #build_name.
@@ -46,8 +47,9 @@ module Mongoid
       def self.define_builder!(association)
         association.inverse_class.tap do |klass|
           klass.re_define_method("build_#{association.name}") do |*args|
-            attributes, _options = parse_args(*args)
-            document = Factory.execute_build(association.relation_class, attributes, execute_callbacks: false)
+            attributes, type, _opts = parse_args(args)
+
+            document = Factory.execute_build(type || association.relation_class, attributes, execute_callbacks: false)
             _building do
               child = send("#{association.name}=", document)
               child.run_pending_callbacks
@@ -70,8 +72,9 @@ module Mongoid
       def self.define_creator!(association)
         association.inverse_class.tap do |klass|
           klass.re_define_method("create_#{association.name}") do |*args|
-            attributes, _options = parse_args(*args)
-            document = Factory.execute_build(association.relation_class, attributes, execute_callbacks: false)
+            attributes, type, _opts = parse_args(args)
+
+            document = Factory.execute_build(type || association.relation_class, attributes, execute_callbacks: false)
             doc = _assigning do
               send("#{association.name}=", document)
             end

data/lib/mongoid/association/constrainable.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Association
-
     # Used for converting foreign key values to the correct type based on the
     # types of ids that the document stores.
     module Constrainable
-
       # Convert the supplied object to the appropriate type to set as the
       # foreign key for an association.
       #
@@ -19,11 +16,12 @@ module Mongoid
       # @return [ Object ] The object cast to the correct type.
       def convert_to_foreign_key(object)
         return convert_polymorphic(object) if polymorphic?
-        field = relation_class.fields["_id"]
+
+        field = relation_class.fields['_id']
         if relation_class.using_object_ids?
           BSON::ObjectId.mongoize(object)
         elsif object.is_a?(::Array)
-          object.map!{ |obj| field.mongoize(obj) }
+          object.map! { |obj| field.mongoize(obj) }
         else
           field.mongoize(object)
         end

data/lib/mongoid/association/depending.rb

@@ -1,9 +1,7 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Association
-
     # This module defines the behavior for setting up cascading deletes and
     # nullifies for associations, and how to delegate to the appropriate strategy.
     module Depending
@@ -12,15 +10,18 @@ module Mongoid
       included do
         class_attribute :dependents
 
+        # Note the leading underscore: without it, ActiveSupport's
+        # class_attribute would generate a helper method for this attribute
+        # that collides with one it generates for :dependents.
+        #
         # @api private
-        class_attribute :dependents_owner
+        class_attribute :_dependents_owner
 
         self.dependents = []
-        self.dependents_owner = self
+        self._dependents_owner = self
       end
 
       class_methods do
-
         # Returns all dependent association metadata objects.
         #
         # @return [ Array<Mongoid::Association::Relatable> ] The dependent
@@ -30,19 +31,20 @@ module Mongoid
         def _all_dependents
           superclass_dependents = superclass.respond_to?(:_all_dependents) ? superclass._all_dependents : []
           dependents + superclass_dependents.reject do |new_dep|
-            dependents.any? do |old_dep| old_dep.name == new_dep.name
+            dependents.any? do |old_dep|
+              old_dep.name == new_dep.name
             end
           end
         end
       end
 
       # The valid dependent strategies.
-      STRATEGIES = [
-          :delete_all,
-          :destroy,
-          :nullify,
-          :restrict_with_exception,
-          :restrict_with_error
+      STRATEGIES = %i[
+        delete_all
+        destroy
+        nullify
+        restrict_with_exception
+        restrict_with_error
       ]
 
       # Attempt to add the cascading information for the document to know how
@@ -57,14 +59,12 @@ module Mongoid
       def self.define_dependency!(association)
         validate!(association)
         association.inverse_class.tap do |klass|
-          if klass.dependents_owner != klass
+          if klass._dependents_owner != klass
             klass.dependents = []
-            klass.dependents_owner = klass
+            klass._dependents_owner = klass
           end
 
-          if association.dependent && !klass.dependents.include?(association)
-            klass.dependents.push(association)
-          end
+          klass.dependents.push(association) if association.dependent && !klass.dependents.include?(association)
         end
       end
 
@@ -77,11 +77,11 @@ module Mongoid
       # @raises [ Mongoid::Errors::InvalidDependentStrategy ]
       #   Error if invalid.
       def self.validate!(association)
-        unless STRATEGIES.include?(association.dependent)
-          raise Errors::InvalidDependentStrategy.new(association,
-                                                     association.dependent,
-                                                     STRATEGIES)
-        end
+        return if STRATEGIES.include?(association.dependent)
+
+        raise Errors::InvalidDependentStrategy.new(association,
+                                                   association.dependent,
+                                                   STRATEGIES)
       end
 
       # Perform all cascading deletes, destroys, or nullifies. Will delegate to
@@ -100,43 +100,43 @@ module Mongoid
       private
 
       def _dependent_delete_all!(association)
-        if relation = send(association.name)
-          if relation.respond_to?(:dependents) && relation.dependents.blank?
-            relation.clear
-          else
-            ::Array.wrap(send(association.name)).each { |rel| rel.delete }
-          end
+        return unless relation = without_autobuild { send(association.name) }
+
+        if relation.respond_to?(:dependents) && relation.dependents.blank?
+          relation.clear
+        else
+          ::Array.wrap(relation).each { |rel| rel.delete }
         end
       end
 
       def _dependent_destroy!(association)
-        if relation = send(association.name)
-          if relation.is_a?(Enumerable)
-            relation.entries
-            relation.each { |doc| doc.destroy }
-          else
-            relation.destroy
-          end
+        return unless relation = without_autobuild { send(association.name) }
+
+        if relation.is_a?(Enumerable)
+          relation.entries
+          relation.each { |doc| doc.destroy }
+        else
+          relation.destroy
         end
       end
 
       def _dependent_nullify!(association)
-        if relation = send(association.name)
-          relation.nullify
-        end
+        return unless relation = without_autobuild { send(association.name) }
+
+        relation.nullify
       end
 
       def _dependent_restrict_with_exception!(association)
-        if (relation = send(association.name)) && !relation.blank?
+        if (relation = without_autobuild { send(association.name) }) && !relation.blank?
           raise Errors::DeleteRestriction.new(relation, association.name)
         end
       end
 
       def _dependent_restrict_with_error!(association)
-        if (relation = send(association.name)) && !relation.blank?
-          errors.add(association.name, :destroy_restrict_with_error_dependencies_exist)
-          throw(:abort, false)
-        end
+        return unless (relation = without_autobuild { send(association.name) }) && !relation.blank?
+
+        errors.add(association.name, :destroy_restrict_with_error_dependencies_exist)
+        throw(:abort, false)
       end
     end
   end

data/lib/mongoid/association/eager.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
-# rubocop:todo all
 
 module Mongoid
   module Association
-
     # Base class for eager load preload functions.
     class Eager
+      # Build a preloader for the given arguments and run it.
+      #
+      # @param (see #initialize)
+      #
+      # @return [ Array ] The list of documents given.
+      def self.run(associations, docs, use_lookup = false, pipeline = [])
+        new(associations, docs, use_lookup, pipeline).run
+      end
+
       # Instantiate the eager load class.
       #
       # @example Create the new belongs to eager load preloader.
@@ -14,12 +21,18 @@ module Mongoid
       # @param [ Array<Mongoid::Association::Relatable> ] associations
       #   Associations to eager load
       # @param [ Array<Document> ] docs Documents to preload the associations
+      # @param [ Boolean ] use_lookup Whether to use $lookup aggregation
+      #   for eager loading. This is used in Criteria#eager_load.
+      # @param [ Array<Hash> ] pipeline The aggregation pipeline to use
+      #   when using $lookup for eager loading.
       #
       # @return [ Base ] The eager load preloader
-      def initialize(associations, docs)
+      def initialize(associations, docs, use_lookup = false, pipeline = [])
         @associations = associations
         @docs = docs
         @grouped_docs = {}
+        @use_lookup = use_lookup
+        @pipeline = pipeline
       end
 
       # Run the preloader.
@@ -30,6 +43,13 @@ module Mongoid
       # @return [ Array ] The list of documents given.
       def run
         @loaded = []
+
+        if @use_lookup
+          preload_with_lookup
+          @loaded = @docs
+          return @loaded.flatten
+        end
+
         while shift_association
           preload
           @loaded << @docs.collect { |d| d.send(@association.name) if d.respond_to?(@association.name) }
@@ -49,6 +69,21 @@ module Mongoid
         raise NotImplementedError
       end
 
+      # Preload the current association using $lookup aggregation.
+      # This method executes the aggregation pipeline
+      # and instantiates the documents.
+      # @example Preload the current association using $lookup.
+      #   loader.preload_with_lookup
+      def preload_with_lookup
+        # For $lookup aggregation, execute pipeline and instantiate documents
+        owner_class = @associations.first.owner_class
+        aggregated_docs = owner_class.collection.aggregate(@pipeline)
+        aggregated_docs.each do |doc|
+          parsed_doc = Factory.from_db(owner_class, doc)
+          @docs << parsed_doc
+        end
+      end
+
       # Retrieves the documents referenced by the association, and
       # yields each one sequentially to the provided block. If the
       # association is not polymorphic, all documents are retrieved in
@@ -64,18 +99,13 @@ module Mongoid
       # When the documents are retrieved, the set of inclusions applied
       # is the set of inclusions applied to the host document minus the
       # association that is being eagerly loaded.
-      private def each_loaded_document_of_class(cls, keys)
-        # Note: keys should not include nil elements.
+      private def each_loaded_document_of_class(cls, keys, &block)
+        # NOTE: keys should not include nil elements.
         # Upstream code is responsible for eliminating nils from keys.
         return cls.none if keys.empty?
 
-        criteria = cls.criteria
-        criteria = criteria.apply_scope(@association.scope)
-        criteria = criteria.any_in(key => keys)
-        criteria.inclusions = criteria.inclusions - [@association]
-        criteria.each do |doc|
-          yield doc
-        end
+        criteria = prepare_criteria_for_loaded_documents(cls, keys)
+        criteria.each(&block)
       end
 
       # Set the pre-loaded document into its parent.
@@ -103,7 +133,7 @@ module Mongoid
       def grouped_docs
         @grouped_docs[@association.name] ||= @docs.group_by do |doc|
           doc.send(group_by_key) if doc.respond_to?(group_by_key)
-        end.reject do |k, v|
+        end.reject do |k, _v|
           k.nil?
         end
       end
@@ -155,6 +185,19 @@ module Mongoid
       def shift_association
         @association = @associations.shift
       end
+
+      # Prepares the criteria to retrieve the documents of the specified
+      # class, that have the foreign key included in the specified list of keys.
+      # When the documents are retrieved, the set of inclusions applied
+      # is the set of inclusions applied to the host document minus the
+      # association that is being eagerly loaded.
+      def prepare_criteria_for_loaded_documents(cls, keys)
+        criteria = cls.criteria
+        criteria = criteria.apply_scope(@association.scope)
+        criteria = criteria.any_in(key => keys)
+        criteria.inclusions = criteria.inclusions - [ @association ]
+        criteria
+      end
     end
   end
 end

data/lib/mongoid/association/eager_load/discriminated_inclusion.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require 'mongoid/association/eager_load/inclusion'
+
+module Mongoid
+  module Association
+    module EagerLoad
+      # Loads an inclusion that more than one subclass defines under the same name
+      # but pointing at different targets. A single $lookup can't serve them: they
+      # would all write to the same field and overwrite one another. So each
+      # subclass's inclusion is contributed into its own temporary field, carrying
+      # its own nested children, and a $set then routes every document to the field
+      # for its own type, by the discriminator.
+      #
+      # For Machine.eager_load(:widgets), where Lathe#widgets => Cog and
+      # Press#widgets => Belt, it emits:
+      #
+      #   { '$lookup' => { 'from' => 'cogs',  ..., 'as' => '__eager_load_widgets_Lathe' } },
+      #   { '$lookup' => { 'from' => 'belts', ..., 'as' => '__eager_load_widgets_Press' } },
+      #   { '$set' => {
+      #     'widgets' => { '$switch' => { 'branches' => [   # route each document to its
+      #       { 'case' => { '$eq' => [ '$_type', 'Lathe' ] }, 'then' => '$__eager_load_widgets_Lathe' },  # own type's matches
+      #       { 'case' => { '$eq' => [ '$_type', 'Press' ] }, 'then' => '$__eager_load_widgets_Press' }
+      #     ], 'default' => [] } }
+      #   } },
+      #   { '$unset' => [ '__eager_load_widgets_Lathe', '__eager_load_widgets_Press' ] }
+      #
+      # @api private
+      class DiscriminatedInclusion < Inclusion
+        def initialize(nodes)
+          super()
+          @nodes = nodes
+        end
+
+        # Append each subclass's lookup (into its own temporary field), the routing
+        # $set, and the cleanup $unset.
+        #
+        # @param [ Array<Hash> ] destination The pipeline the stages are appended to.
+        def contribute(destination, _chain)
+          fields = @nodes.map { |node| [ node, contribute_into_temporary(destination, node) ] }
+          destination << route_by_type(fields)
+          destination << { '$unset' => fields.map { |_node, field| field } }
+        end
+
+        private
+
+        # Let the node build its own $lookup (with its nested children) and redirect
+        # it to write into a temporary field instead of the shared association name.
+        def contribute_into_temporary(destination, node)
+          field = temporary_field(node)
+          captured = []
+          node.contribute(captured, [])
+          captured.first['$lookup']['as'] = field
+          destination.concat(captured)
+          field
+        end
+
+        def temporary_field(node)
+          "__eager_load_#{node.association.name}_#{owner(node).discriminator_value}"
+        end
+
+        # The $set that fills the association on each document from the temporary
+        # field matching its own type.
+        def route_by_type(fields)
+          branches = fields.map do |node, field|
+            {
+              'case' => { '$eq' => [ "$#{discriminator_key}", owner(node).discriminator_value ] },
+              'then' => "$#{field}"
+            }
+          end
+          { '$set' => { name => { '$switch' => { 'branches' => branches, 'default' => [] } } } }
+        end
+
+        def owner(node)
+          node.association.inverse_class
+        end
+
+        def name
+          @nodes.first.association.name.to_s
+        end
+
+        def discriminator_key
+          owner(@nodes.first).discriminator_key
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/association/eager_load/embedded_distributor.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+    # Objects that carry out the aggregation-based eager load triggered by
+    # Criteria#eager_load.
+    module EagerLoad
+      # Distributes the results of a $lookup onto the embedded documents they
+      # belong to.
+      #
+      # A $lookup overwrites the single field it writes to, and it can't distribute
+      # its matches across the elements of an embedded array. So when the reference
+      # being eager-loaded lives on an embedded document, the matches are first
+      # collected in a temporary top-level field and then distributed down the
+      # embedded path onto each embedded document, merging into it (so the rest of
+      # the document is kept) and correlating by key. The temporary field is then
+      # dropped.
+      #
+      # For Computer.eager_load(port: :device) (Port belongs_to :device) it emits:
+      #
+      #   { '$lookup' => {                     # devices can't be written into
+      #     'from' => 'devices',               # the embedded port, so they are
+      #     'localField' => 'port.device_id',  # collected in a temp top-level
+      #     'foreignField' => '_id',           # field instead
+      #     'as' => '__eager_load_port_device'
+      #   } },
+      #   { '$set' => {
+      #     'port' => { '$mergeObjects' => [   # merge a 'device' key onto the port
+      #       '$port',
+      #       { 'device' => { '$filter' => { ... } } }   # this port's matches
+      #     ] }
+      #   } },
+      #   { '$unset' => '__eager_load_port_device' }  # drop the temp field
+      #
+      # @api private
+      class EmbeddedDistributor
+        # @param [ Mongoid::Association::Relatable ] association The referenced
+        #   inclusion being eager-loaded from within an embedded document.
+        # @param [ Array<Mongoid::Association::Relatable> ] chain The embedded
+        #   ancestors, from the root document inward, down to the association's owner.
+        # @param [ Hash ] lookup_stage The $lookup stage built for the association.
+        #
+        # @return [ EmbeddedDistributor ] The distributor.
+        class << self
+          def for(association:, chain:, lookup_stage:)
+            lookup = lookup_stage['$lookup']
+            new(association, chain, lookup_stage, lookup['localField'], lookup['foreignField'])
+          end
+
+          private :new
+        end
+
+        def initialize(association, chain, lookup_stage, local_field, foreign_field)
+          @association = association
+          @chain = chain
+          @lookup_stage = lookup_stage
+          @local_field = local_field
+          @foreign_field = foreign_field
+        end
+
+        # The stages that run the $lookup into a temporary field and then
+        # distribute its matches onto the embedded documents along the path.
+        #
+        # @return [ Array<Hash> ] The stages to append to the pipeline.
+        def stages
+          redirect_lookup_to_temporary_field
+          [
+            @lookup_stage,
+            { '$set' => {
+              root => distributed_value(@chain, "$#{root}")
+            } },
+            { '$unset' => temporary_field }
+          ]
+        end
+
+        private
+
+        # The $lookup runs at the top level, so it reads the local field by its
+        # full embedded path and writes the matches into the temporary field.
+        def redirect_lookup_to_temporary_field
+          lookup = @lookup_stage['$lookup']
+          lookup['localField'] = "#{path}.#{@local_field}"
+          lookup['as'] = temporary_field
+        end
+
+        def path
+          @chain.map(&:store_as).join('.')
+        end
+
+        def root
+          @chain.first.store_as
+        end
+
+        def temporary_field
+          "__eager_load_#{path.tr('.', '_')}_#{@association.name}"
+        end
+
+        # An embedded collection (embeds_many) is rebuilt with $map so each element
+        # keeps its own matches instead of collapsing onto the first; a single
+        # embedded document (embeds_one) receives its matches in place.
+        def distributed_value(chain, node)
+          head, *rest = chain
+          many = head.many?
+          element = many ? "$$#{head.store_as}" : node
+          child =
+            if rest.empty?
+              { @association.name.to_s => correlated_matches(element) }
+            else
+              segment = rest.first.store_as
+              { segment => distributed_value(rest, "#{element}.#{segment}") }
+            end
+          merged = { '$mergeObjects' => [ element, child ] }
+          return merge_into_present(node, merged) unless many
+
+          { '$map' => {
+            'input' => node,
+            'as' => head.store_as,
+            'in' => merged
+          } }
+        end
+
+        # Merge the matches into a single embedded document only when it exists, so
+        # an absent embeds_one stays absent instead of being synthesized from its
+        # matches alone.
+        def merge_into_present(node, merged)
+          { '$cond' => {
+            'if' => { '$ifNull' => [ node, false ] },
+            'then' => merged,
+            'else' => node
+          } }
+        end
+
+        # The matches that belong to a single embedded element.
+        def correlated_matches(element)
+          { '$filter' => {
+            'input' => "$#{temporary_field}",
+            'as' => 'match',
+            'cond' => { match_operator => [ "$$match.#{@foreign_field}", "#{element}.#{@local_field}" ] }
+          } }
+        end
+
+        # A has_and_belongs_to_many holds an array of foreign keys, so a match
+        # belongs when its key is among them ($in); every other association points
+        # at a single key ($eq).
+        def match_operator
+          @association.many_to_many? ? '$in' : '$eq'
+        end
+      end
+    end
+  end
+end