mongoid 8.0.6 → 8.1.0

data/lib/mongoid/contextual/mongo.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "mongoid/contextual/mongo/documents_loader"
 require "mongoid/contextual/atomic"
 require "mongoid/contextual/aggregable/mongo"
 require "mongoid/contextual/command"
@@ -37,6 +38,18 @@ module Mongoid
       # @attribute [r] view The Mongo collection view.
       attr_reader :view
 
+      # Run an explain on the criteria.
+      #
+      # @example Explain the criteria.
+      #   Band.where(name: "Depeche Mode").explain
+      #
+      # @param [ Hash ] options customizable options (See Mongo::Collection::View::Explainable)
+      #
+      # @return [ Hash ] The explain result.
+      def_delegator :view, :explain
+
+      attr_reader :documents_loader
+
       # Get the number of documents matching the query.
       #
       # @example Get the number of matching documents.
@@ -154,22 +167,28 @@ module Mongoid
       # @example Do any documents exist for the context.
       #   context.exists?
       #
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.exists?(name: "...")
+      #
       # @note We don't use count here since Mongo does not use counted
       #   b-tree indexes.
       #
-      # @return [ true | false ] If the count is more than zero.
-      def exists?
-        !!(view.projection(_id: 1).limit(1).first)
-      end
-
-      # Run an explain on the criteria.
-      #
-      # @example Explain the criteria.
-      #   Band.where(name: "Depeche Mode").explain
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
       #
-      # @return [ Hash ] The explain result.
-      def explain
-        view.explain
+      # @return [ true | false ] If the count is more than zero.
+      #   Always false if passed nil or false.
+      def exists?(id_or_conditions = :none)
+        return false if self.view.limit == 0
+        case id_or_conditions
+        when :none then !!(view.projection(_id: 1).limit(1).first)
+        when nil, false then false
+        when Hash then Mongo.new(criteria.where(id_or_conditions)).exists?
+        else Mongo.new(criteria.where(_id: id_or_conditions)).exists?
+        end
       end
 
       # Execute the find and modify command, used for MongoDB's
@@ -225,28 +244,6 @@ module Mongoid
         end
       end
 
-      # Get the first document in the database for the criteria's selector.
-      #
-      # @example Get the first document.
-      #   context.first
-      #
-      # @note Automatically adding a sort on _id when no other sort is
-      #   defined on the criteria has the potential to cause bad performance issues.
-      #   If you experience unexpected poor performance when using #first or #last
-      #   and have no sort defined on the criteria, use #take instead.
-      #   Be aware that #take won't guarantee order.
-      #
-      # @param [ Integer ] limit The number of documents to return.
-      #
-      # @return [ Document ] The first document.
-      def first(limit = nil)
-        sort = view.sort || { _id: 1 }
-        if raw_docs = view.sort(sort).limit(limit || 1).to_a
-          process_raw_docs(raw_docs, limit)
-        end
-      end
-      alias :one :first
-
       # Return the first result without applying sort
       #
       # @api private
@@ -297,25 +294,6 @@ module Mongoid
 
       def_delegator :@klass, :database_field_name
 
-      # Get the last document in the database for the criteria's selector.
-      #
-      # @example Get the last document.
-      #   context.last
-      #
-      # @note Automatically adding a sort on _id when no other sort is
-      #   defined on the criteria has the potential to cause bad performance issues.
-      #   If you experience unexpected poor performance when using #first or #last
-      #   and have no sort defined on the criteria, use #take instead.
-      #   Be aware that #take won't guarantee order.
-      #
-      # @param [ Integer ] limit The number of documents to return.
-      #
-      # @return [ Document ] The last document.
-      def last(limit = nil)
-        raw_docs = view.sort(inverse_sorting).limit(limit || 1).to_a.reverse
-        process_raw_docs(raw_docs, limit)
-      end
-
       # Returns the number of documents in the database matching
       # the query selector.
       #
@@ -340,44 +318,6 @@ module Mongoid
         @view = view.limit(value) and self
       end
 
-      # Take the given number of documents from the database.
-      #
-      # @example Take 10 documents
-      #   context.take(10)
-      #
-      # @param [ Integer | nil ] limit The number of documents to return or nil.
-      #
-      # @return [ Document | Array<Document> ] The list of documents, or one
-      #   document if no value was given.
-      def take(limit = nil)
-        if limit
-          limit(limit).to_a
-        else
-          # Do to_a first so that the Mongo#first method is not used and the
-          # result is not sorted.
-          limit(1).to_a.first
-        end
-      end
-
-      # Take one document from the database and raise an error if there are none.
-      #
-      # @example Take a document
-      #   context.take!
-      #
-      # @return [ Document ] The document.
-      #
-      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
-      #   documents to take.
-      def take!
-        # Do to_a first so that the Mongo#first method is not used and the
-        # result is not sorted.
-        if fst = limit(1).to_a.first
-          fst
-        else
-          raise Errors::DocumentNotFound.new(klass, nil, nil)
-        end
-      end
-
       # Initiate a map/reduce operation from the context.
       #
       # @example Initiate a map/reduce.
@@ -391,15 +331,22 @@ module Mongoid
         MapReduce.new(collection, criteria, map, reduce)
       end
 
-      # Pluck the single field values from the database. Will return duplicates
-      # if they exist and only works for top level fields.
+      # Pluck the field value(s) from the database. Returns one
+      # result for each document found in the database for
+      # the context. The results are normalized according to their
+      # Mongoid field types. Note that the results may include
+      # duplicates and nil values.
       #
       # @example Pluck a field.
       #   context.pluck(:_id)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pluck.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck,
+      #   which may include nested fields using dot-notation.
       #
       # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
+      #   If the *fields arg contains a single value, each result
+      #   in the array will be a single value. Otherwise, each
+      #   result in the array will be an array of values.
       def pluck(*fields)
         # Multiple fields can map to the same field name. For example, plucking
         # a field and its _translations field map to the same field in the database.
@@ -434,13 +381,51 @@ module Mongoid
       # @example Pick a field.
       #   context.pick(:_id)
       #
-      # @param [ String | Symbol ] *fields Field(s) to pick.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pick.
       #
       # @return [ Object | Array<Object> ] The picked values.
       def pick(*fields)
         limit(1).pluck(*fields).first
       end
 
+      # Take the given number of documents from the database.
+      #
+      # @example Take 10 documents
+      #   context.take(10)
+      #
+      # @param [ Integer | nil ] limit The number of documents to return or nil.
+      #
+      # @return [ Document | Array<Document> ] The list of documents, or one
+      #   document if no value was given.
+      def take(limit = nil)
+        if limit
+          limit(limit).to_a
+        else
+          # Do to_a first so that the Mongo#first method is not used and the
+          # result is not sorted.
+          limit(1).to_a.first
+        end
+      end
+
+      # Take one document from the database and raise an error if there are none.
+      #
+      # @example Take a document
+      #   context.take!
+      #
+      # @return [ Document ] The document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def take!
+        # Do to_a first so that the Mongo#first method is not used and the
+        # result is not sorted.
+        if fst = limit(1).to_a.first
+          fst
+        else
+          raise Errors::DocumentNotFound.new(klass, nil, nil)
+        end
+      end
+
       # Get a hash of counts for the values of a single field. For example,
       # if the following documents were in the database:
       #
@@ -553,7 +538,7 @@ module Mongoid
       # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
       #   an update should apply.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update(attributes = nil, opts = {})
         update_documents(attributes, :update_one, opts)
       end
@@ -569,11 +554,255 @@ module Mongoid
       # @option opts [ Array ] :array_filters A set of filters specifying to which array elements
       #   an update should apply.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update_all(attributes = nil, opts = {})
         update_documents(attributes, :update_many, opts)
       end
 
+      # Get the first document in the database for the criteria's selector.
+      #
+      # @example Get the first document.
+      #   context.first
+      #
+      # @note Automatically adding a sort on _id when no other sort is
+      #   defined on the criteria has the potential to cause bad performance issues.
+      #   If you experience unexpected poor performance when using #first or #last
+      #   and have no sort defined on the criteria, use #take instead.
+      #   Be aware that #take won't guarantee order.
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document | nil ] The first document or nil if none is found.
+      def first(limit = nil)
+        if limit.nil?
+          retrieve_nth(0)
+        else
+          retrieve_nth_with_limit(0, limit)
+        end
+      end
+      alias :one :first
+
+      # Get the first document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the first document.
+      #   context.first!
+      #
+      # @note Automatically adding a sort on _id when no other sort is
+      #   defined on the criteria has the potential to cause bad performance issues.
+      #   If you experience unexpected poor performance when using #first! or #last!
+      #   and have no sort defined on the criteria, use #take! instead.
+      #   Be aware that #take! won't guarantee order.
+      #
+      # @return [ Document ] The first document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents available.
+      def first!
+        first || raise_document_not_found_error
+      end
+
+      # Get the last document in the database for the criteria's selector.
+      #
+      # @example Get the last document.
+      #   context.last
+      #
+      # @note Automatically adding a sort on _id when no other sort is
+      #   defined on the criteria has the potential to cause bad performance issues.
+      #   If you experience unexpected poor performance when using #first or #last
+      #   and have no sort defined on the criteria, use #take instead.
+      #   Be aware that #take won't guarantee order.
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document | nil ] The last document or nil if none is found.
+      def last(limit = nil)
+        if limit.nil?
+          retrieve_nth_to_last(0)
+        else
+          retrieve_nth_to_last_with_limit(0, limit)
+        end
+      end
+
+      # Get the last document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the last document.
+      #   context.last!
+      #
+      # @note Automatically adding a sort on _id when no other sort is
+      #   defined on the criteria has the potential to cause bad performance issues.
+      #   If you experience unexpected poor performance when using #first! or #last!
+      #   and have no sort defined on the criteria, use #take! instead.
+      #   Be aware that #take! won't guarantee order.
+      #
+      # @return [ Document ] The last document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents available.
+      def last!
+        last || raise_document_not_found_error
+      end
+
+      # Get the second document in the database for the criteria's selector.
+      #
+      # @example Get the second document.
+      #   context.second
+      #
+      # @return [ Document | nil ] The second document or nil if none is found.
+      def second
+        retrieve_nth(1)
+      end
+
+      # Get the second document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the second document.
+      #   context.second!
+      #
+      # @return [ Document ] The second document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents available.
+      def second!
+        second || raise_document_not_found_error
+      end
+
+      # Get the third document in the database for the criteria's selector.
+      #
+      # @example Get the third document.
+      #   context.third
+      #
+      # @return [ Document | nil ] The third document or nil if none is found.
+      def third
+        retrieve_nth(2)
+      end
+
+      # Get the third document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the third document.
+      #   context.third!
+      #
+      # @return [ Document ] The third document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents available.
+      def third!
+        third || raise_document_not_found_error
+      end
+
+      # Get the fourth document in the database for the criteria's selector.
+      #
+      # @example Get the fourth document.
+      #   context.fourth
+      #
+      # @return [ Document | nil ] The fourth document or nil if none is found.
+      def fourth
+        retrieve_nth(3)
+      end
+
+      # Get the fourth document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the fourth document.
+      #   context.fourth!
+      #
+      # @return [ Document ] The fourth document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents available.
+      def fourth!
+        fourth || raise_document_not_found_error
+      end
+
+      # Get the fifth document in the database for the criteria's selector.
+      #
+      # @example Get the fifth document.
+      #   context.fifth
+      #
+      # @return [ Document | nil ] The fifth document or nil if none is found.
+      def fifth
+        retrieve_nth(4)
+      end
+
+      # Get the fifth document in the database for the criteria's selector or
+      # raise an error if none is found.
+      #
+      # @example Get the fifth document.
+      #   context.fifth!
+      #
+      # @return [ Document ] The fifth document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents available.
+      def fifth!
+        fifth || raise_document_not_found_error
+      end
+
+      # Get the second to last document in the database for the criteria's
+      # selector.
+      #
+      # @example Get the second to last document.
+      #   context.second_to_last
+      #
+      # @return [ Document | nil ] The second to last document or nil if none
+      # is found.
+      def second_to_last
+        retrieve_nth_to_last(1)
+      end
+
+      # Get the second to last document in the database for the criteria's
+      # selector or raise an error if none is found.
+      #
+      # @example Get the second to last document.
+      #   context.second_to_last!
+      #
+      # @return [ Document ] The second to last document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents available.
+      def second_to_last!
+        second_to_last || raise_document_not_found_error
+      end
+
+      # Get the third to last document in the database for the criteria's
+      # selector.
+      #
+      # @example Get the third to last document.
+      #   context.third_to_last
+      #
+      # @return [ Document | nil ] The third to last document or nil if none
+      # is found.
+      def third_to_last
+        retrieve_nth_to_last(2)
+      end
+
+      # Get the third to last document in the database for the criteria's
+      # selector or raise an error if none is found.
+      #
+      # @example Get the third to last document.
+      #   context.third_to_last!
+      #
+      # @return [ Document ] The third to last document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents available.
+      def third_to_last!
+        third_to_last || raise_document_not_found_error
+      end
+
+      # Schedule a task to load documents for the context.
+      #
+      # Depending on the Mongoid configuration, the scheduled task can be executed
+      # immediately on the caller's thread, or can be scheduled for an
+      # asynchronous execution.
+      #
+      # @api private
+      def load_async
+        @documents_loader ||= DocumentsLoader.new(view, klass, criteria)
+      end
+
       private
 
       # Update the documents for the provided method.
@@ -641,24 +870,29 @@ module Mongoid
         Hash[sort.map{|k, v| [k, -1*v]}]
       end
 
-      # Get the documents the context should iterate. This follows 3 rules:
+      # Get the documents the context should iterate.
       #
-      # 1. If the query is cached, and we already have documents loaded, use
-      #   them.
-      # 2. If we are eager loading, then eager load the documents and use
-      #   those.
-      # 3. Use the query.
-      #
-      # @api private
-      #
-      # @example Get the documents for iteration.
-      #   context.documents_for_iteration
+      # If the documents have been already preloaded by `Document::Loader`
+      # instance, they will be used.
       #
       # @return [ Array<Document> | Mongo::Collection::View ] The docs to iterate.
+      #
+      # @api private
       def documents_for_iteration
-        return view unless eager_loadable?
-        docs = view.map{ |doc| Factory.from_db(klass, doc, criteria) }
-        eager_load(docs)
+        if @documents_loader
+          if @documents_loader.started?
+            @documents_loader.value!
+          else
+            @documents_loader.unschedule
+            @documents_loader.execute
+          end
+        else
+          return view unless eager_loadable?
+          docs = view.map do |doc|
+            Factory.from_db(klass, doc, criteria)
+          end
+          eager_load(docs)
+        end
       end
 
       # Yield to the document.
@@ -677,8 +911,6 @@ module Mongoid
         yield(doc)
       end
 
-      private
-
       def _session
         @criteria.send(:_session)
       end
@@ -813,6 +1045,34 @@ module Mongoid
         docs = eager_load(docs)
         limit ? docs : docs.first
       end
+
+      def raise_document_not_found_error
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
+
+      def retrieve_nth(n)
+        retrieve_nth_with_limit(n, 1).first
+      end
+
+      def retrieve_nth_with_limit(n, limit)
+        sort = view.sort || { _id: 1 }
+        v = view.sort(sort).limit(limit || 1)
+        v = v.skip(n) if n > 0
+        if raw_docs = v.to_a
+          process_raw_docs(raw_docs, limit)
+        end
+      end
+
+      def retrieve_nth_to_last(n)
+        retrieve_nth_to_last_with_limit(n, 1).first
+      end
+
+      def retrieve_nth_to_last_with_limit(n, limit)
+        v = view.sort(inverse_sorting).skip(n).limit(limit || 1)
+        v = v.skip(n) if n > 0
+        raw_docs = v.to_a.reverse
+        process_raw_docs(raw_docs, limit)
+      end
     end
   end
 end