mongoid 7.4.0 → 8.0.3

data/lib/mongoid/contextual/aggregable/memory.rb

@@ -9,7 +9,7 @@ module Mongoid
         # Get all the aggregate values for the provided field.
         # Provided for interface consistency with Aggregable::Mongo.
         #
-        # @param [ String, Symbol ] field The field name.
+        # @param [ String | Symbol ] field The field name.
         #
         # @return [ Hash ] A Hash containing the aggregate values.
         #   If no documents are present, then returned Hash will have
@@ -27,9 +27,13 @@ module Mongoid
         #
         # @param [ Symbol ] field The field to average.
         #
-        # @return [ Float ] The average.
+        # @return [ Numeric ] The average.
         def avg(field)
-          count > 0 ? sum(field).to_f / count.to_f : nil
+          total = count { |doc| !doc.send(field).nil? }
+          return nil unless total > 0
+
+          total = total.to_f if total.is_a?(Integer)
+          sum(field) / total
         end
 
         # Get the max value of the provided field. If provided a block, will
@@ -46,10 +50,12 @@ module Mongoid
         #
         # @param [ Symbol ] field The field to max.
         #
-        # @return [ Float, Document ] The max value or document with the max
+        # @return [ Numeric | Document ] The max value or document with the max
         #   value.
         def max(field = nil)
-          block_given? ? super() : aggregate_by(field, :max_by)
+          return super() if block_given?
+
+          aggregate_by(field, :max)
         end
 
         # Get the min value of the provided field. If provided a block, will
@@ -66,10 +72,12 @@ module Mongoid
         #
         # @param [ Symbol ] field The field to min.
         #
-        # @return [ Float, Document ] The min value or document with the min
+        # @return [ Numeric | Document ] The min value or document with the min
         #   value.
         def min(field = nil)
-          block_given? ? super() : aggregate_by(field, :min_by)
+          return super() if block_given?
+
+          aggregate_by(field, :min)
         end
 
         # Get the sum value of the provided field. If provided a block, will
@@ -83,13 +91,11 @@ module Mongoid
         #
         # @param [ Symbol ] field The field to sum.
         #
-        # @return [ Float ] The sum value.
+        # @return [ Numeric ] The sum value.
         def sum(field = nil)
-          if block_given?
-            super()
-          else
-            count > 0 ? super(0) { |doc| doc.public_send(field) } : 0
-          end
+          return super() if block_given?
+
+          aggregate_by(field, :sum) || 0
         end
 
         private
@@ -99,14 +105,16 @@ module Mongoid
         # @api private
         #
         # @example Aggregate by the field and method.
-        #   aggregable.aggregate_by(:name, :min_by)
+        #   aggregable.aggregate_by(:likes, :min_by)
         #
         # @param [ Symbol ] field The field to aggregate on.
         # @param [ Symbol ] method The method (min_by or max_by).
         #
-        # @return [ Integer ] The aggregate.
+        # @return [ Numeric | nil ] The aggregate.
         def aggregate_by(field, method)
-          count > 0 ? send(method) { |doc| doc.public_send(field) }.public_send(field) : nil
+          return nil unless any?
+
+          map { |doc| doc.public_send(field) }.compact.public_send(method)
         end
       end
     end

data/lib/mongoid/contextual/aggregable/mongo.rb

@@ -20,13 +20,13 @@ module Mongoid
         #   #   "avg" => 750.0
         #   # }
         #
-        # @param [ String, Symbol ] field The field name.
+        # @param [ String | Symbol ] field The field name.
         #
         # @return [ Hash ] A Hash containing the aggregate values.
         #   If no documents are found, then returned Hash will have
         #   count, sum of 0 and max, min, avg of nil.
         def aggregates(field)
-          result = collection.find.aggregate(pipeline(field), session: _session).to_a
+          result = collection.aggregate(pipeline(field), session: _session).to_a
           if result.empty?
             if Mongoid.broken_aggregables
               { "count" => 0, "sum" => nil, "avg" => nil, "min" => nil, "max" => nil }
@@ -64,7 +64,7 @@ module Mongoid
         #
         # @param [ Symbol ] field The field to max.
         #
-        # @return [ Float, Document ] The max value or document with the max
+        # @return [ Float | Document ] The max value or document with the max
         #   value.
         def max(field = nil)
           block_given? ? super() : aggregates(field)["max"]
@@ -84,7 +84,7 @@ module Mongoid
         #
         # @param [ Symbol ] field The field to min.
         #
-        # @return [ Float, Document ] The min value or document with the min
+        # @return [ Float | Document ] The min value or document with the min
         #   value.
         def min(field = nil)
           block_given? ? super() : aggregates(field)["min"]
@@ -115,7 +115,7 @@ module Mongoid
         # @example Get the pipeline.
         #   aggregable.pipeline(:likes)
         #
-        # @param [ String, Symbol ] field The name of the field.
+        # @param [ String | Symbol ] field The name of the field.
         #
         # @return [ Array ] The array of pipeline operators.
         def pipeline(field)

data/lib/mongoid/contextual/aggregable/none.rb

@@ -11,7 +11,7 @@ module Mongoid
         # Get all the aggregate values for the provided field in null context.
         # Provided for interface consistency with Aggregable::Mongo.
         #
-        # @param [ String, Symbol ] _field The field name.
+        # @param [ String | Symbol ] _field The field name.
         #
         # @return [ Hash ] A Hash with count, sum of 0 and max, min, avg of nil.
         def aggregates(_field)

data/lib/mongoid/contextual/atomic.rb

@@ -150,7 +150,7 @@ module Mongoid
       # @example Unset the field on the matches.
       #   context.unset(:name)
       #
-      # @param [ String | Symbol | Array<String|Symbol> | Hash ] args
+      # @param [ String | Symbol | Array<String | Symbol> | Hash ] args
       #   The name(s) of the field(s) to unset.
       #   If a Hash is specified, its keys will be used irrespective of what
       #   each key's value is, even if the value is nil or false.

data/lib/mongoid/contextual/geo_near.rb

@@ -16,7 +16,7 @@ module Mongoid
       # @example Get the average distance.
       #   geo_near.average_distance
       #
-      # @return [ Float, nil ] The average distance.
+      # @return [ Float | nil ] The average distance.
       def average_distance
         average = stats["avgDistance"]
         (average.nil? || average.nan?) ? nil : average
@@ -46,7 +46,7 @@ module Mongoid
       # @example Provide the distance multiplier.
       #   geo_near.distance_multiplier(13113.1)
       #
-      # @param [ Integer, Float ] value The distance multiplier.
+      # @param [ Integer | Float ] value The distance multiplier.
       #
       # @return [ GeoNear ] The GeoNear wrapper.
       def distance_multiplier(value)
@@ -98,9 +98,9 @@ module Mongoid
       # @example Get the max distance.
       #   geo_near.max_distance
       #
-      # @param [ Integer, Float ] value The maximum distance.
+      # @param [ Integer | Float ] value The maximum distance.
       #
-      # @return [ GeoNear, Float ] The GeoNear command or the value.
+      # @return [ GeoNear | Float ] The GeoNear command or the value.
       def max_distance(value = nil)
         if value
           command[:maxDistance] = value
@@ -115,7 +115,7 @@ module Mongoid
       # @example Set the min distance.
       #   geo_near.min_distance(0.5)
       #
-      # @param [ Integer, Float ] value The minimum distance.
+      # @param [ Integer | Float ] value The minimum distance.
       #
       # @return [ GeoNear ] The GeoNear command.
       def min_distance(value)
@@ -139,7 +139,7 @@ module Mongoid
       # @example Set the unique flag.
       #   geo_near.unique(false)
       #
-      # @param [ true, false ] value Whether to return unique documents.
+      # @param [ true | false ] value Whether to return unique documents.
       #
       # @return [ GeoNear ] The command.
       def unique(value = true)
@@ -211,7 +211,7 @@ module Mongoid
       # @example Get the documents.
       #   geo_near.documents
       #
-      # @return [ Array, Cursor ] The documents.
+      # @return [ Array | Cursor ] The documents.
       def documents
         results["results"].map do |attributes|
           doc = Factory.from_db(criteria.klass, attributes["obj"], criteria)

data/lib/mongoid/contextual/map_reduce.rb

@@ -121,7 +121,7 @@ module Mongoid
       # @return [ MapReduce ] The map/reduce object.
       def out(location)
         normalized = location.dup
-        normalized.update_values do |value|
+        normalized.transform_values! do |value|
           value.is_a?(::Symbol) ? value.to_s : value
         end
         @map_reduce = @map_reduce.out(normalized)
@@ -147,7 +147,7 @@ module Mongoid
       def raw
         validate_out!
         cmd = command
-        opts = { read: cmd.delete(:read) } if cmd[:read]
+        opts = { read: criteria.options.fetch(:read) } if criteria.options[:read]
         @map_reduce.database.command(cmd, (opts || {}).merge(session: _session)).first
       end
       alias :results :raw

data/lib/mongoid/contextual/memory.rb

@@ -25,7 +25,7 @@ module Mongoid
       #
       # @param [ Array ] other The other array.
       #
-      # @return [ true, false ] If the objects are equal.
+      # @return [ true | false ] If the objects are equal.
       def ==(other)
         return false unless other.respond_to?(:entries)
         entries == other.entries
@@ -74,11 +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.
       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
@@ -106,9 +110,9 @@ module Mongoid
       # @example Do any documents exist for the context.
       #   context.exists?
       #
-      # @return [ true, false ] If the count is more than zero.
+      # @return [ true | false ] If the count is more than zero.
       def exists?
-        count > 0
+        any?
       end
 
       # Get the first document in the database for the criteria's selector.
@@ -116,9 +120,15 @@ module Mongoid
       # @example Get the first document.
       #   context.first
       #
+      # @param [ Integer ] limit The number of documents to return.
+      #
       # @return [ Document ] The first document.
-      def first(*args)
-        eager_load([documents.first]).first
+      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
@@ -159,9 +169,48 @@ 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
-        eager_load([documents.last]).first
+      def last(limit = nil)
+        if limit
+          eager_load(documents.last(limit))
+        else
+          eager_load([documents.last]).first
+        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.
+      #
+      # @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.
@@ -182,21 +231,58 @@ module Mongoid
       #
       # @param [ Integer ] value The number of documents to return.
       #
-      # @return [ Mongo ] The context.
+      # @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
 
       # Skips the provided number of documents.
@@ -206,7 +292,7 @@ module Mongoid
       #
       # @param [ Integer ] value The number of documents to skip.
       #
-      # @return [ Mongo ] The context.
+      # @return [ Memory ] The context.
       def skip(value)
         self.skipping = value
         self
@@ -220,7 +306,7 @@ module Mongoid
       # @param [ Hash ] values The sorting values as field/direction(1/-1)
       #   pairs.
       #
-      # @return [ Mongo ] The context.
+      # @return [ Memory ] The context.
       def sort(values)
         in_place_sort(values) and self
       end
@@ -232,7 +318,7 @@ module Mongoid
       #
       # @param [ Hash ] attributes The new attributes for the document.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update(attributes = nil)
         update_documents(attributes, [ first ])
       end
@@ -244,7 +330,7 @@ module Mongoid
       #
       # @param [ Hash ] attributes The new attributes for each document.
       #
-      # @return [ nil, false ] False if no attributes were provided.
+      # @return [ nil | false ] False if no attributes were provided.
       def update_all(attributes = nil)
         update_documents(attributes, entries)
       end
@@ -414,6 +500,79 @@ 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
     end
   end
 end