mongoid 7.3.5 → 7.5.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"
@@ -27,8 +26,6 @@ module Mongoid
       # @param [ Array ] other The other array.
       #
       # @return [ true, false ] If the objects are equal.
-      #
-      # @since 3.0.0
       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|
@@ -84,10 +77,12 @@ module Mongoid
       # @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|
@@ -118,8 +111,6 @@ module Mongoid
       #   context.exists?
       #
       # @return [ true, false ] If the count is more than zero.
-      #
-      # @since 3.0.0
       def exists?
         count > 0
       end
@@ -129,11 +120,16 @@ module Mongoid
       # @example Get the first document.
       #   context.first
       #
-      # @return [ Document ] The first document.
+      # @param [ Integer | Hash ] limit_or_opts The number of documents to
+      #   return, or a hash of options.
       #
-      # @since 3.0.0
-      def first(*args)
-        eager_load([documents.first]).first
+      # @return [ Document ] The first document.
+      def first(limit_or_opts = nil)
+        if limit_or_opts.nil? || limit_or_opts.is_a?(Hash)
+          eager_load([documents.first]).first
+        else
+          eager_load(documents.first(limit_or_opts))
+        end
       end
       alias :one :first
       alias :find_first :first
@@ -144,8 +140,6 @@ module Mongoid
       #   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 +159,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 +170,52 @@ module Mongoid
       # @example Get the last document.
       #   context.last
       #
+      # @param [ Integer | Hash ] limit_or_opts The number of documents to
+      #   return, or a hash of options.
+      #
+      # @option limit_or_opts [ :none ] :id_sort This option is deprecated.
+      #   Don't apply a sort on _id if no other sort is defined on the criteria.
+      #
       # @return [ Document ] The last document.
+      def last(limit_or_opts = nil)
+        if limit_or_opts.nil? || limit_or_opts.is_a?(Hash)
+          eager_load([documents.last]).first
+        else
+          eager_load(documents.last(limit_or_opts))
+        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.
+      #
+      # @example Take a document.
+      #   context.take
+      #
+      # @return [ Document ] The document.
       #
-      # @since 3.0.0
-      def last
-        eager_load([documents.last]).first
+      # @raises [ Mongoid::Errors::DocumentNotFound ] raises when there are no
+      #   documents to take.
+      def take!
+        if documents.empty?
+          raise Errors::DocumentNotFound.new(klass, nil, nil)
+        else
+          eager_load([documents.first]).first
+        end
       end
 
       # Get the length of matching documents in the context.
@@ -191,8 +224,6 @@ module Mongoid
       #   context.length
       #
       # @return [ Integer ] The matching length.
-      #
-      # @since 3.0.0
       def length
         documents.length
       end
@@ -206,22 +237,41 @@ module Mongoid
       # @param [ Integer ] value The number of documents to return.
       #
       # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
       def limit(value)
         self.limiting = value
         self
       end
 
       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 |d|
+            if fields.length == 1
+              retrieve_value_at_path(d, fields.first)
+            else
+              fields.map do |field|
+                retrieve_value_at_path(d, field)
+              end
+            end
           end
-        end.compact
+        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
 
       # Skips the provided number of documents.
@@ -232,8 +282,6 @@ module Mongoid
       # @param [ Integer ] value The number of documents to skip.
       #
       # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
       def skip(value)
         self.skipping = value
         self
@@ -248,8 +296,6 @@ module Mongoid
       #   pairs.
       #
       # @return [ Mongo ] The context.
-      #
-      # @since 3.0.0
       def sort(values)
         in_place_sort(values) and self
       end
@@ -262,8 +308,6 @@ module Mongoid
       # @param [ Hash ] attributes The new attributes for the document.
       #
       # @return [ nil, false ] False if no attributes were provided.
-      #
-      # @since 3.0.0
       def update(attributes = nil)
         update_documents(attributes, [ first ])
       end
@@ -276,8 +320,6 @@ module Mongoid
       # @param [ Hash ] attributes The new attributes for each document.
       #
       # @return [ nil, false ] False if no attributes were provided.
-      #
-      # @since 3.0.0
       def update_all(attributes = nil)
         update_documents(attributes, entries)
       end
@@ -292,8 +334,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 +351,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 +370,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 +383,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 +419,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 +428,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 +445,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 +459,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 +476,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 +489,63 @@ 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
     end
   end
 end