Mark eager-load internals @api private and restore Eager's public API

The new eager-load classes are implementation detail, so mark them @api
private, and add YARD to the public methods that lacked it.

Removing parameters from Eager#initialize changed its public API. Keep the
use_lookup/pipeline parameters and the $lookup branch in #run, and have
preload_for_lookup delegate to a new Eager.run class method that wraps
new(...).run.

Update the eager_spec warning expectation for the new cluster/database message.

Author: cperezabo

lib/mongoid/association/eager.rb

@@ -4,6 +4,15 @@ 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.
@@ -12,12 +21,18 @@ class Eager
       # @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.
@@ -29,6 +44,12 @@ def initialize(associations, docs)
       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) }
@@ -48,6 +69,21 @@ def preload
         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

lib/mongoid/association/eager_load/discriminated_inclusion.rb

@@ -24,6 +24,8 @@ module EagerLoad
       #     ], 'default' => [] } }
       #   } },
       #   { '$unset' => [ '__eager_load_widgets_Lathe', '__eager_load_widgets_Press' ] }
+      #
+      # @api private
       class DiscriminatedInclusion < Inclusion
         def initialize(nodes)
           super()

lib/mongoid/association/eager_load/embedded_distributor.rb

@@ -31,6 +31,8 @@ module EagerLoad
       #     ] }
       #   } },
       #   { '$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.

lib/mongoid/association/eager_load/inclusion.rb

@@ -8,6 +8,8 @@ module EagerLoad
       # tree follows by recursion. AssociationInclusion stands for a single
       # association; DiscriminatedInclusion stands for a name several subclasses
       # share.
+      #
+      # @api private
       class Inclusion
         # Add this inclusion's stages to the destination.
         #
@@ -23,6 +25,8 @@ def contribute(destination, chain)
       # An inclusion that stands for a single association. The LookupPipeline holds
       # the stage-building helpers the kinds lean on, and a node carries its own
       # children, so the pipeline is built by recursion from the roots downward.
+      #
+      # @api private
       class AssociationInclusion < Inclusion
         class << self
           # Builds the right kind of inclusion for the association. Each subclass
@@ -39,6 +43,8 @@ def for(association, pipeline, children)
 
           # Whether this kind handles the given association.
           #
+          # @param [ Mongoid::Association::Relatable ] association The inclusion.
+          #
           # @return [ true | false ] Whether it handles it.
           def for?(association)
             raise NotImplementedError
@@ -75,15 +81,28 @@ def initialize(association, pipeline, children)
       #       <children>
       #     ]
       #   } }
+      #
+      # @api private
       class JoinedInclusion < AssociationInclusion
         class << self
           # The default kind: a referenced, non-polymorphic association, i.e. the
           # one no sibling kind claims.
+          #
+          # @param [ Mongoid::Association::Relatable ] association The inclusion.
+          #
+          # @return [ true | false ] Whether it handles it.
           def for?(association)
             (superclass.subclasses - [ self ]).none? { |kind| kind.for?(association) }
           end
         end
 
+        # Append the $lookup, with the children in its sub-pipeline, to the
+        # destination; or distribute it onto the embedded path when nested in one.
+        #
+        # @param [ Array<Hash> ] destination The pipeline (or sub-pipeline) the
+        #   stages are appended to.
+        # @param [ Array<Mongoid::Association::Relatable> ] chain The embedded path
+        #   accumulated from the ancestors above this inclusion (empty at the top).
         def contribute(destination, chain)
           stage = @pipeline.lookup_stage_for(@association)
           @children.each { |child| child.contribute(stage['$lookup']['pipeline'], []) }
@@ -103,13 +122,25 @@ def contribute(destination, chain)
       # For Computer.eager_load(port: :device) the :port inclusion emits nothing;
       # it hands the path [ :port ] to :device, which EmbeddedDistributor then
       # turns into stages.
+      #
+      # @api private
       class EmbeddedInclusion < AssociationInclusion
         class << self
+          # @param [ Mongoid::Association::Relatable ] association The inclusion.
+          #
+          # @return [ true | false ] Whether the association is embedded.
           def for?(association)
             association.embedded?
           end
         end
 
+        # Add no stage of its own; hand this document down the embedded path so the
+        # children distribute onto it.
+        #
+        # @param [ Array<Hash> ] destination The pipeline (or sub-pipeline) the
+        #   stages are appended to.
+        # @param [ Array<Mongoid::Association::Relatable> ] chain The embedded path
+        #   accumulated from the ancestors above this inclusion (empty at the top).
         def contribute(destination, chain)
           @children.each { |child| child.contribute(destination, chain + [ @association ]) }
         end
@@ -118,13 +149,23 @@ def contribute(destination, chain)
       # A polymorphic inclusion: its target collection varies per document, so it
       # can't be a $lookup. It adds nothing here; PolymorphicPreloader resolves it
       # after the roots are materialized.
+      #
+      # @api private
       class DeferredInclusion < AssociationInclusion
         class << self
+          # @param [ Mongoid::Association::Relatable ] association The inclusion.
+          #
+          # @return [ true | false ] Whether the association is polymorphic.
           def for?(association)
             association.polymorphic?
           end
         end
 
+        # Add nothing; PolymorphicPreloader resolves the association after the
+        # roots are materialized.
+        #
+        # @param [ Array<Hash> ] destination The pipeline (unused).
+        # @param [ Array<Mongoid::Association::Relatable> ] chain The embedded path (unused).
         def contribute(destination, chain); end
       end
     end

lib/mongoid/association/eager_load/inclusion_tree.rb

@@ -14,8 +14,16 @@ module EagerLoad
       # inclusion is removed as it is placed, so it lands once per branch even if
       # more than one parent in that branch points at it, and a circular chain of
       # inclusions can't loop forever.
+      #
+      # @api private
       class InclusionTree
         class << self
+          # Builds the tree for the criteria's inclusions.
+          #
+          # @param [ Array<Mongoid::Association::Relatable> ] inclusions The inclusions.
+          # @param [ LookupPipeline ] pipeline The pipeline being built.
+          #
+          # @return [ InclusionTree ] The tree.
           def from(inclusions, pipeline)
             new(inclusions, pipeline, inclusions.to_h { |association| [ association.name, association ] })
           end

lib/mongoid/association/eager_load/lookup_pipeline.rb

@@ -36,6 +36,8 @@ module EagerLoad
       #         } }
       #       ]
       #     } } ]
+      #
+      # @api private
       class LookupPipeline
         def initialize(criteria)
           @criteria = criteria

lib/mongoid/association/eager_load/polymorphic_preloader.rb

@@ -11,6 +11,8 @@ module EagerLoad
       # collection varies per document. So once the roots are materialized, the
       # foreign keys are grouped by type, PolymorphicTargets resolves the documents
       # for those keys, and the result is set on each document.
+      #
+      # @api private
       class PolymorphicPreloader
         def initialize(association, root_class)
           @association = association

lib/mongoid/association/eager_load/polymorphic_targets.rb

@@ -7,12 +7,19 @@ module EagerLoad
       # { type => { primary_key => document } }. Each subclass reaches the types that
       # live in one place (the root's database or elsewhere); .for resolves the whole
       # set, routing each type to the subclass that can reach it.
+      #
+      # @api private
       class PolymorphicTargets
         class << self
           # Resolve every polymorphic target for the foreign keys grouped by type.
           # The types whose documents share the root's database are fetched together
           # in one $facet; those living elsewhere are read through their own models.
-          # Returns them indexed as { type => { primary_key => document } }.
+          #
+          # @param [ Mongoid::Association::Relatable ] association The polymorphic inclusion.
+          # @param [ Hash ] keys_by_type The foreign keys grouped by type.
+          # @param [ Class ] root_class The class being queried.
+          #
+          # @return [ Hash ] The targets, as { type => { primary_key => document } }.
           def for(association, keys_by_type, root_class)
             here, elsewhere = keys_by_type.partition do |type, _keys|
               in_root_database?(association, type, root_class)
@@ -73,12 +80,15 @@ def indexed(documents, model)
       #       'Scanner' => [ { '$lookup' => { 'from' => 'scanners', ... } }, ... ]
       #     } }
       #   ]
+      #
+      # @api private
       class SameDatabaseTargets < PolymorphicTargets
         def initialize(association, keys_by_type, root_class)
           super(association, keys_by_type)
           @root_class = root_class
         end
 
+        # @return [ Hash ] The targets, as { type => { primary_key => document } }.
         def fetch
           return {} if @keys_by_type.empty?
 
@@ -124,7 +134,10 @@ def branch_for(collection_name, keys)
       #
       # For { 'Scanner' => [ id2 ] } it runs, on the Scanner model's own client:
       #   scanners.find('_id' => { '$in' => [ id2 ] })
+      #
+      # @api private
       class OtherDatabaseTargets < PolymorphicTargets
+        # @return [ Hash ] The targets, as { type => { primary_key => document } }.
         def fetch
           @keys_by_type.to_h do |type, keys|
             model = model_for(type)

lib/mongoid/association/eager_loadable.rb

@@ -119,8 +119,7 @@ def preload(associations, docs)
       # @return [ Array<Mongoid::Document> ] The materialized root documents.
       def preload_for_lookup(criteria)
         pipeline = EagerLoad::LookupPipeline.new(criteria).stages
-        owner = criteria.inclusions.first.owner_class
-        owner.collection.aggregate(pipeline).map { |document| Factory.from_db(owner, document) }
+        Eager.run(criteria.inclusions, [], true, pipeline)
       end
 
       private