mongoid 7.1.1 → 8.1.0

data/lib/mongoid/contextual/memory.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/contextual/aggregable/memory"
 require "mongoid/association/eager_loadable"
@@ -26,9 +25,7 @@ module Mongoid
       #
       # @param [ Array ] other The other array.
       #
-      # @return [ true, false ] If the objects are equal.
-      #
-      # @since 3.0.0
+      # @return [ true | false ] If the objects are equal.
       def ==(other)
         return false unless other.respond_to?(:entries)
         entries == other.entries
@@ -40,8 +37,6 @@ module Mongoid
       #   context.delete
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def delete
         deleted = count
         removed = map do |doc|
@@ -64,8 +59,6 @@ module Mongoid
       #   context.destroy
       #
       # @return [ nil ] Nil.
-      #
-      # @since 3.0.0
       def destroy
         deleted = count
         each do |doc|
@@ -81,13 +74,15 @@ module Mongoid
       # @example Get the distinct values.
       #   context.distinct(:name)
       #
-      # @param [ String, Symbol ] field The name of the field.
+      # @param [ String | Symbol ] field The name of the field.
       #
       # @return [ Array<Object> ] The distinct values for the field.
-      #
-      # @since 3.0.0
       def distinct(field)
-        documents.map{ |doc| doc.send(field) }.uniq
+        if Mongoid.legacy_pluck_distinct
+          documents.map{ |doc| doc.send(field) }.uniq
+        else
+          pluck(field).uniq
+        end
       end
 
       # Iterate over the context. If provided a block, yield to a Mongoid
@@ -99,8 +94,6 @@ module Mongoid
       #   end
       #
       # @return [ Enumerator ] The enumerator.
-      #
-      # @since 3.0.0
       def each
         if block_given?
           documents_for_iteration.each do |doc|
@@ -117,11 +110,24 @@ module Mongoid
       # @example Do any documents exist for the context.
       #   context.exists?
       #
-      # @return [ true, false ] If the count is more than zero.
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.exists?(name: "...")
       #
-      # @since 3.0.0
-      def exists?
-        count > 0
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
+      #
+      # @return [ true | false ] If the count is more than zero.
+      #   Always false if passed nil or false.
+      def exists?(id_or_conditions = :none)
+        case id_or_conditions
+        when :none then any?
+        when nil, false then false
+        when Hash then Memory.new(criteria.where(id_or_conditions)).exists?
+        else Memory.new(criteria.where(_id: id_or_conditions)).exists?
+        end
       end
 
       # Get the first document in the database for the criteria's selector.
@@ -129,23 +135,39 @@ module Mongoid
       # @example Get the first document.
       #   context.first
       #
-      # @return [ Document ] The first document.
+      # @param [ Integer ] limit The number of documents to return.
       #
-      # @since 3.0.0
-      def first(*args)
-        eager_load([documents.first]).first
+      # @return [ Document ] The first document.
+      def first(limit = nil)
+        if limit
+          eager_load(documents.first(limit))
+        else
+          eager_load([documents.first]).first
+        end
       end
       alias :one :first
       alias :find_first :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!
+      #
+      # @return [ Document ] The first document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def first!
+        first || raise_document_not_found_error
+      end
+
       # Create the new in memory context.
       #
       # @example Create the new context.
       #   Memory.new(criteria)
       #
       # @param [ Criteria ] criteria The criteria.
-      #
-      # @since 3.0.0
       def initialize(criteria)
         @criteria, @klass = criteria, criteria.klass
         @documents = criteria.documents.select do |doc|
@@ -165,8 +187,6 @@ module Mongoid
       # @param [ Hash ] incs The operations.
       #
       # @return [ Enumerator ] The enumerator.
-      #
-      # @since 7.0.0
       def inc(incs)
         each do |document|
           document.inc(incs)
@@ -178,11 +198,29 @@ module Mongoid
       # @example Get the last document.
       #   context.last
       #
+      # @param [ Integer ] limit The number of documents to return.
+      #
       # @return [ Document ] The last document.
+      def last(limit = nil)
+        if limit
+          eager_load(documents.last(limit))
+        else
+          eager_load([documents.last]).first
+        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!
       #
-      # @since 3.0.0
-      def last
-        eager_load([documents.last]).first
+      # @return [ Document ] The last document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def last!
+        last || raise_document_not_found_error
       end
 
       # Get the length of matching documents in the context.
@@ -191,8 +229,6 @@ module Mongoid
       #   context.length
       #
       # @return [ Integer ] The matching length.
-      #
-      # @since 3.0.0
       def length
         documents.length
       end
@@ -205,23 +241,88 @@ module Mongoid
       #
       # @param [ Integer ] value The number of documents to return.
       #
-      # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
+      # @return [ Memory ] The context.
       def limit(value)
         self.limiting = value
         self
       end
 
+      # Pluck the field values in memory.
+      #
+      # @example Get the values in memory.
+      #   context.pluck(:name)
+      #
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
+      #
+      # @return [ Array<Object> | Array<Array<Object>> ] The plucked values.
       def pluck(*fields)
-        fields = Array.wrap(fields)
-        documents.map do |doc|
-          if fields.size == 1
-            doc[fields.first]
-          else
-            fields.map { |n| doc[n] }.compact
+        if Mongoid.legacy_pluck_distinct
+          documents.pluck(*fields)
+        else
+          documents.map do |doc|
+            pluck_from_doc(doc, *fields)
           end
-        end.compact
+        end
+      end
+
+      # Pick the field values in memory.
+      #
+      # @example Get the values in memory.
+      #   context.pick(:name)
+      #
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pick.
+      #
+      # @return [ Object | Array<Object> ] The picked values.
+      def pick(*fields)
+        if doc = documents.first
+          pluck_from_doc(doc, *fields)
+        end
+      end
+
+      # Tally the field values in memory.
+      #
+      # @example Get the counts of values in memory.
+      #   context.tally(:name)
+      #
+      # @param [ String | Symbol ] field Field to tally.
+      #
+      # @return [ Hash ] The hash of counts.
+      def tally(field)
+        return documents.each_with_object({}) do |d, acc|
+          v = retrieve_value_at_path(d, field)
+          acc[v] ||= 0
+          acc[v] += 1
+        end
+      end
+
+      # Take the given number of documents from the database.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @param [ Integer | nil ] limit The number of documents to take or nil.
+      #
+      # @return [ Document ] The document.
+      def take(limit = nil)
+        if limit
+          eager_load(documents.take(limit))
+        else
+          eager_load([documents.first]).first
+        end
+      end
+
+      # Take the given number of documents from the database or raise an error
+      # if none are found.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @return [ Document ] The document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def take!
+        take || raise_document_not_found_error
       end
 
       # Skips the provided number of documents.
@@ -231,9 +332,7 @@ module Mongoid
       #
       # @param [ Integer ] value The number of documents to skip.
       #
-      # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
+      # @return [ Memory ] The context.
       def skip(value)
         self.skipping = value
         self
@@ -247,9 +346,7 @@ module Mongoid
       # @param [ Hash ] values The sorting values as field/direction(1/-1)
       #   pairs.
       #
-      # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
+      # @return [ Memory ] The context.
       def sort(values)
         in_place_sort(values) and self
       end
@@ -261,9 +358,7 @@ module Mongoid
       #
       # @param [ Hash ] attributes The new attributes for the document.
       #
-      # @return [ nil, false ] False if no attributes were provided.
-      #
-      # @since 3.0.0
+      # @return [ nil | false ] False if no attributes were provided.
       def update(attributes = nil)
         update_documents(attributes, [ first ])
       end
@@ -275,13 +370,167 @@ module Mongoid
       #
       # @param [ Hash ] attributes The new attributes for each document.
       #
-      # @return [ nil, false ] False if no attributes were provided.
-      #
-      # @since 3.0.0
+      # @return [ nil | false ] False if no attributes were provided.
       def update_all(attributes = nil)
         update_documents(attributes, entries)
       end
 
+      # Get the second document in the database for the criteria's selector.
+      #
+      # @example Get the second document.
+      #   context.second
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The second document.
+      def second
+        eager_load([documents.second]).first
+      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 to take.
+      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
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The third document.
+      def third
+        eager_load([documents.third]).first
+      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 to take.
+      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
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The fourth document.
+      def fourth
+        eager_load([documents.fourth]).first
+      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 to take.
+      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
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The fifth document.
+      def fifth
+        eager_load([documents.fifth]).first
+      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 to take.
+      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
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The second to last document.
+      def second_to_last
+        eager_load([documents.second_to_last]).first
+      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 to take.
+      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
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @return [ Document ] The third to last document.
+      def third_to_last
+        eager_load([documents.third_to_last]).first
+      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 to take.
+      def third_to_last!
+        third_to_last || raise_document_not_found_error
+      end
+
       private
 
       # Get the documents the context should iterate. This follows 3 rules:
@@ -292,8 +541,6 @@ module Mongoid
       #   context.documents_for_iteration
       #
       # @return [ Array<Document> ] The docs to iterate.
-      #
-      # @since 3.1.0
       def documents_for_iteration
         docs = documents[skipping || 0, limiting || documents.length] || []
         if eager_loadable?
@@ -311,8 +558,6 @@ module Mongoid
       #
       # @param [ Hash ] attributes The attributes.
       # @param [ Array<Document> ] docs The docs to update.
-      #
-      # @since 3.0.4
       def update_documents(attributes, docs)
         return false if !attributes || docs.empty?
         updates = { "$set" => {}}
@@ -332,8 +577,6 @@ module Mongoid
       # @example Get the limiting value.
       #
       # @return [ Integer ] The limit.
-      #
-      # @since 3.0.0
       def limiting
         defined?(@limiting) ? @limiting : nil
       end
@@ -347,36 +590,30 @@ module Mongoid
       # @param [ Integer ] value The limit.
       #
       # @return [ Integer ] The limit.
-      #
-      # @since 3.0.0
       def limiting=(value)
         @limiting = value
       end
 
-      # Get the skiping value.
+      # Get the skipping value.
       #
       # @api private
       #
-      # @example Get the skiping value.
+      # @example Get the skipping value.
       #
       # @return [ Integer ] The skip.
-      #
-      # @since 3.0.0
       def skipping
         defined?(@skipping) ? @skipping : nil
       end
 
-      # Set the skiping value.
+      # Set the skipping value.
       #
       # @api private
       #
-      # @example Set the skiping value.
+      # @example Set the skipping value.
       #
       # @param [ Integer ] value The skip.
       #
       # @return [ Integer ] The skip.
-      #
-      # @since 3.0.0
       def skipping=(value)
         @skipping = value
       end
@@ -389,8 +626,6 @@ module Mongoid
       #   context.apply_options
       #
       # @return [ Memory ] self.
-      #
-      # @since 3.0.0
       def apply_options
         raise Errors::InMemoryCollationNotSupported.new if criteria.options[:collation]
         skip(criteria.options[:skip]).limit(criteria.options[:limit])
@@ -400,8 +635,6 @@ module Mongoid
       #
       # @example Apply the sorting params.
       #   context.apply_sorting
-      #
-      # @since 3.0.0
       def apply_sorting
         if spec = criteria.options[:sort]
           in_place_sort(spec)
@@ -419,8 +652,6 @@ module Mongoid
       # @param [ Object ] b The first object.
       #
       # @return [ Integer ] The comparison value.
-      #
-      # @since 3.0.0
       def compare(a, b)
         case
         when a.nil? then b.nil? ? 0 : 1
@@ -435,8 +666,6 @@ module Mongoid
       #   context.in_place_sort(name: 1)
       #
       # @param [ Hash ] values The field/direction sorting pairs.
-      #
-      # @since 3.0.0
       def in_place_sort(values)
         documents.sort! do |a, b|
           values.map do |field, direction|
@@ -454,8 +683,6 @@ module Mongoid
       #   context.prepare_remove(doc)
       #
       # @param [ Document ] doc The document.
-      #
-      # @since 3.0.0
       def prepare_remove(doc)
         @selector ||= root.atomic_selector
         @path ||= doc.atomic_path
@@ -469,6 +696,83 @@ module Mongoid
       def _session
         @criteria.send(:_session)
       end
+
+      # Retrieve the value for the current document at the given field path.
+      #
+      # For example, if I have the following models:
+      #
+      #   User has_many Accounts
+      #   address is a hash on Account
+      #
+      #   u = User.new(accounts: [ Account.new(address: { street: "W 50th" }) ])
+      #   retrieve_value_at_path(u, "user.accounts.address.street")
+      #   # => [ "W 50th" ]
+      #
+      # Note that the result is in an array since accounts is an array. If it
+      # was nested in two arrays the result would be in a 2D array.
+      #
+      # @param [ Object ] document The object to traverse the field path.
+      # @param [ String ] field_path The dotted string that represents the path
+      #   to the value.
+      #
+      # @return [ Object | nil ] The value at the given field path or nil if it
+      #   doesn't exist.
+      def retrieve_value_at_path(document, field_path)
+        return if field_path.blank? || !document
+        segment, remaining = field_path.to_s.split('.', 2)
+
+        curr = if document.is_a?(Document)
+          # Retrieves field for segment to check localization. Only does one
+          # iteration since there's no dots
+          res = if remaining
+            field = document.class.traverse_association_tree(segment)
+            # If this is a localized field, and there are remaining, get the
+            # _translations hash so that we can get the specified translation in
+            # the remaining
+            if field&.localized?
+              document.send("#{segment}_translations")
+            end
+          end
+          meth = klass.aliased_associations[segment] || segment
+          res.nil? ? document.try(meth) : res
+        elsif document.is_a?(Hash)
+          # TODO: Remove the indifferent access when implementing MONGOID-5410.
+          document.key?(segment.to_s) ?
+            document[segment.to_s] :
+            document[segment.to_sym]
+        else
+          nil
+        end
+
+        return curr unless remaining
+
+        if curr.is_a?(Array)
+          # compact is used for consistency with server behavior.
+          curr.map { |d| retrieve_value_at_path(d, remaining) }.compact
+        else
+          retrieve_value_at_path(curr, remaining)
+        end
+      end
+
+      # Pluck the field values from the given document.
+      #
+      # @param [ Document ] doc The document to pluck from.
+      # @param [ [ String | Symbol ]... ] *fields Field(s) to pluck.
+      #
+      # @return [ Object | Array<Object> ] The plucked values.
+      def pluck_from_doc(doc, *fields)
+        if fields.length == 1
+          retrieve_value_at_path(doc, fields.first)
+        else
+          fields.map do |field|
+            retrieve_value_at_path(doc, field)
+          end
+        end
+      end
+
+      def raise_document_not_found_error
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
     end
   end
 end