mongoid 7.4.3 → 7.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9706abdd1325c02319659ad86963770019a8559220f411ec6a98207d41e6388
-  data.tar.gz: 99026d1acf68f1a4347607fad2374462b7bf1ea5b42c268180a2ede163c707a0
+  metadata.gz: 32597c6d6b536f273850be1989db0d876026d2bffda067d7923f173c3966faa6
+  data.tar.gz: 97fffa62c90ae5c20e7dcf00eb151b557c26ab5ae676c45b5651efa5143cf34c
 SHA512:
-  metadata.gz: 42224a7effb0349e39934d79191af29dd1f77802cb6a273c44312edba01aba0a46c07061577660f223d0b09211141c843a68827ef9cb5453ed3bfb1d9764ca8c
-  data.tar.gz: be7fff7159b76d9827ee3b5e28c78313098895ecd63047e478992709c975e05579fb6a0b7a9444bbc8f4451284948af585f76b987975c3ad16dbd0aabafe0e48
+  metadata.gz: dbe0c003a7e058f5ab6ac5592170ef1a26e02bf9be729b889c55a3a70af4e0c8b6e52f7157cc9b40879545689972769bae5deabf6814ce1ebeb97fdf1a128212
+  data.tar.gz: d696cd95560d51b34318e7f25467450dde8461383dd17830f1177363cbf006c863b1268a2b79616e563343a3fd0e388c9d3bde67821b698b4cf0035bbfc9b719

data/lib/config/locales/en.yml

@@ -404,6 +404,13 @@ en:
             \_\_\_\_\_\_default:\n
             \_\_\_\_\_\_\_\_hosts:\n
             \_\_\_\_\_\_\_\_\_\_- localhost:27017\n\n"
+        no_documents_found:
+          message: "Could not find a document of class %{klass}."
+          summary: "Mongoid attempted to find a document of the class %{klass}
+            but none exist."
+          resolution: "Create a document of class %{klass} or use a finder
+            method that returns nil when no documents are found instead of
+            raising an exception."
         no_environment:
           message: "Could not load the configuration since no environment
             was defined."

data/lib/mongoid/association/embedded/batchable.rb

@@ -80,8 +80,7 @@ module Mongoid
         def batch_replace(docs)
           if docs.blank?
             if _assigning? && !empty?
-              _base.delayed_atomic_sets.delete(path)
-              clear_atomic_path_cache
+              _base.delayed_atomic_sets.clear
               _base.add_atomic_unset(first)
               target_duplicate = _target.dup
               pre_process_batch_remove(target_duplicate, :delete)
@@ -93,8 +92,7 @@ module Mongoid
             _base.delayed_atomic_sets.clear unless _assigning?
             docs = normalize_docs(docs).compact
             _target.clear and _unscoped.clear
-            _base.delayed_atomic_unsets.delete(path)
-            clear_atomic_path_cache
+            _base.delayed_atomic_unsets.clear
             inserts = execute_batch_set(docs)
             add_atomic_sets(inserts)
           end
@@ -236,22 +234,7 @@ module Mongoid
         #
         # @return [ String ] The atomic path.
         def path
-          @path ||= if _unscoped.empty?
-            Mongoid::Atomic::Paths::Embedded::Many.position_without_document(_base, _association)
-          else
-            _unscoped.first.atomic_path
-          end
-        end
-
-        # Clear the cache for path and atomic_paths. This method is used when
-        # the path method is used, and the association has not been set on the
-        # document yet, which can cause path and atomic_paths to be calculated
-        # incorrectly later.
-        #
-        # @api private
-        def clear_atomic_path_cache
-          self.path = nil
-          _base.instance_variable_set("@atomic_paths", nil)
+          @path ||= _unscoped.first.atomic_path
         end
 
         # Set the atomic path.

data/lib/mongoid/association/macros.rb

@@ -12,6 +12,26 @@ module Mongoid
         class_attribute :embedded, instance_reader: false
         class_attribute :embedded_relations
         class_attribute :relations
+
+        # A hash that maps aliases to their associations. This hash maps the
+        # associations "in database name" to its "in code" name. This is used when
+        # associations specify the `store_as` option, or on a referenced association.
+        # On a referenced association, this is used to map the foreign key to
+        # the association's name. For example, if we had the following
+        # relationship:
+        #
+        #   User has_many Accounts
+        #
+        # User will have an entry in the aliased associations hash:
+        #
+        #   account_ids => accounts
+        #
+        # Note that on the belongs_to associations, the mapping from
+        # foreign key => name is not in the aliased_associations hash, but a
+        # mapping from name => foreign key is in the aliased_fields hash.
+        #
+        # @return [ Hash<String, String> ] The aliased associations hash.
+        #
         # @api private
         class_attribute :aliased_associations
         self.embedded = false

data/lib/mongoid/association/referenced/has_many/enumerable.rb

@@ -243,14 +243,16 @@ module Mongoid
           #   use the option { id_sort: :none }.
           #   Be aware that #first/#last won't guarantee order in this case.
           #
-          # @param [ Hash ] opts The options for the query returning the first document.
+          # @param [ Integer | Hash ] limit_or_opts The number of documents to
+          #   return, or a hash of options.
           #
-          # @option opts [ :none ] :id_sort Don't apply a sort on _id.
+          # @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 first document found.
-          def first(opts = {})
+          def first(limit_or_opts = nil)
             _loaded.try(:values).try(:first) ||
-                _added[(ul = _unloaded.try(:first, opts)).try(:_id)] ||
+                _added[(ul = _unloaded.try(:first, limit_or_opts)).try(:_id)] ||
                 ul ||
                 _added.values.try(:first)
           end
@@ -330,15 +332,17 @@ module Mongoid
           #   use the option { id_sort: :none }.
           #   Be aware that #first/#last won't guarantee order in this case.
           #
-          # @param [ Hash ] opts The options for the query returning the first document.
+          # @param [ Integer | Hash ] limit_or_opts The number of documents to
+          #   return, or a hash of options.
           #
-          # @option opts [ :none ] :id_sort Don't apply a sort on _id.
+          # @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 found.
-          def last(opts = {})
+          def last(limit_or_opts = nil)
             _added.values.try(:last) ||
                 _loaded.try(:values).try(:last) ||
-                _added[(ul = _unloaded.try(:last, opts)).try(:_id)] ||
+                _added[(ul = _unloaded.try(:last, limit_or_opts)).try(:_id)] ||
                 ul
           end
 

data/lib/mongoid/association/referenced/has_many/proxy.rb

@@ -469,8 +469,8 @@ module Mongoid
             selector = conditions || {}
             removed = klass.send(method, selector.merge!(criteria.selector))
             _target.delete_if do |doc|
-              doc._matches?(selector).tap do |b|
-                unbind_one(doc) if b
+              if doc._matches?(selector)
+                unbind_one(doc) and true
               end
             end
             removed

data/lib/mongoid/atomic/paths/embedded/many.rb

@@ -34,25 +34,6 @@ module Mongoid
             locator = document.new_record? ? "" : ".#{document._index}"
             "#{pos}#{"." unless pos.blank?}#{document._association.store_as}#{locator}"
           end
-
-          class << self
-
-            # Get the position of where the document would go for the given
-            # association. The use case for this function is when trying to
-            # persist an empty list for an embedded association. All of the
-            # existing functions for getting the position to store a document
-            # require passing in a document to store, which we don't have when
-            # trying to store the empty list.
-            #
-            # @param [ Document ] parent The parent document to store in.
-            # @param [ Association ] association The association.
-            #
-            # @return [ String ] The position string.
-            def position_without_document(parent, association)
-              pos = parent.atomic_position
-              "#{pos}#{"." unless pos.blank?}#{association.store_as}"
-            end
-          end
         end
       end
     end

data/lib/mongoid/config.rb

@@ -23,7 +23,8 @@ module Mongoid
     # database name is not explicitly defined.
     option :app_name, default: nil
 
-    # Create indexes in background by default.
+    # (Deprecated) In MongoDB 4.0 and earlier, set whether to create
+    # indexes in the background by default. (default: false)
     option :background_indexing, default: false
 
     # Mark belongs_to associations as required by default, so that saving a
@@ -111,6 +112,10 @@ module Mongoid
     # demongoize the values on returning them.
     option :legacy_pluck_distinct, default: true
 
+    # Combine chained operators, which use the same field and operator,
+    # using and's instead of overwriting them.
+    option :overwrite_chained_operators, default: true
+
     # Has Mongoid been configured? This is checking that at least a valid
     # client config exists.
     #

data/lib/mongoid/contextual/memory.rb

@@ -78,7 +78,11 @@ module Mongoid
       #
       # @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
@@ -116,9 +120,16 @@ module Mongoid
       # @example Get the first document.
       #   context.first
       #
+      # @param [ Integer | Hash ] limit_or_opts The number of documents to
+      #   return, or a hash of options.
+      #
       # @return [ Document ] The first document.
-      def first(*args)
-        eager_load([documents.first]).first
+      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
@@ -159,9 +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
-        eager_load([documents.last]).first
+      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.
+      #
+      # @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.
@@ -189,14 +243,35 @@ module Mongoid
       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.
@@ -414,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

data/lib/mongoid/contextual/mongo.rb

@@ -42,6 +42,7 @@ module Mongoid
       #
       # @return [ true, false ] If the context is cached.
       def cached?
+        Mongoid::Warnings.warn_criteria_cache_deprecated
         !!@cache
       end
 
@@ -251,25 +252,28 @@ module Mongoid
       #   and have no sort defined on the criteria, use the option { id_sort: :none }.
       #   Be aware that #first/#last won't guarantee order in this case.
       #
-      # @param [ Hash ] opts The options for the query returning the first document.
+      # @param [ Integer | Hash ] limit_or_opts The number of documents to
+      #   return, or a hash of options.
       #
-      # @option opts [ :none ] :id_sort Don't apply a sort on _id if no other sort
-      #   is defined on the criteria.
+      # @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 first document.
-      def first(opts = {})
-        return documents.first if cached? && cache_loaded?
-        try_cache(:first) do
-          if sort = view.sort || ({ _id: 1 } unless opts[:id_sort] == :none)
-            if raw_doc = view.sort(sort).limit(1).first
-              doc = Factory.from_db(klass, raw_doc, criteria)
-              eager_load([doc]).first
-            end
-          else
-            if raw_doc = view.limit(1).first
-              doc = Factory.from_db(klass, raw_doc, criteria)
-              eager_load([doc]).first
-            end
+      def first(limit_or_opts = nil)
+        limit = limit_or_opts unless limit_or_opts.is_a?(Hash)
+        if cached? && cache_loaded?
+          return limit ? documents.first(limit) : documents.first
+        end
+        try_numbered_cache(:first, limit) do
+          if limit_or_opts.try(:key?, :id_sort)
+            Mongoid::Warnings.warn_id_sort_deprecated
+          end
+          sorted_view = view
+          if sort = view.sort || ({ _id: 1 } unless limit_or_opts.try(:fetch, :id_sort) == :none)
+            sorted_view = view.sort(sort)
+          end
+          if raw_docs = sorted_view.limit(limit || 1).to_a
+            process_raw_docs(raw_docs, limit)
           end
         end
       end
@@ -325,6 +329,10 @@ module Mongoid
       #
       # @return [ Array ] The result of mapping.
       def map(field = nil, &block)
+        if !field.nil?
+          Mongoid::Warnings.warn_map_field_deprecated
+        end
+
         if block_given?
           super(&block)
         else
@@ -360,19 +368,26 @@ module Mongoid
       #   and have no sort defined on the criteria, use the option { id_sort: :none }.
       #   Be aware that #first/#last won't guarantee order in this case.
       #
-      # @param [ Hash ] opts The options for the query returning the first document.
+      # @param [ Integer | Hash ] limit_or_opts The number of documents to
+      #   return, or a hash of options.
       #
-      # @option opts [ :none ] :id_sort Don't apply a sort on _id if no other sort
-      #   is defined on the criteria.
-      def last(opts = {})
-        try_cache(:last) do
-          with_inverse_sorting(opts) do
-            if raw_doc = view.limit(1).first
-              doc = Factory.from_db(klass, raw_doc, criteria)
-              eager_load([doc]).first
+      # @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)
+        limit = limit_or_opts unless limit_or_opts.is_a?(Hash)
+        if cached? && cache_loaded?
+          return limit ? documents.last(limit) : documents.last
+        end
+        res = try_numbered_cache(:last, limit) do
+          with_inverse_sorting(limit_or_opts) do
+            if raw_docs = view.limit(limit || 1).to_a
+              process_raw_docs(raw_docs, limit)
             end
           end
         end
+        res.is_a?(Array) ? res.reverse : res
       end
 
       # Get's the number of documents matching the query selector.
@@ -398,6 +413,44 @@ 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.
@@ -534,6 +587,31 @@ module Mongoid
         end
       end
 
+      # yield the block given or return the cached value
+      #
+      # @param [ String, Symbol ] key The instance variable name
+      # @param [ Integer | nil ] n The number of documents requested or nil
+      #   if none is requested.
+      #
+      # @return [ Object ] The result of the block.
+      def try_numbered_cache(key, n, &block)
+        unless cached?
+          yield if block_given?
+        else
+          len = n || 1
+          ret = instance_variable_get("@#{key}")
+          if !ret || ret.length < len
+            instance_variable_set("@#{key}", ret = Array.wrap(yield))
+          elsif !n
+            ret.is_a?(Array) ? ret.first : ret
+          elsif ret.length > len
+            ret.first(n)
+          else
+            ret
+          end
+        end
+      end
+
       # Update the documents for the provided method.
       #
       # @api private
@@ -598,8 +676,10 @@ module Mongoid
       # @example Apply the inverse sorting params to the given block
       #   context.with_inverse_sorting
       def with_inverse_sorting(opts = {})
+        Mongoid::Warnings.warn_id_sort_deprecated if opts.try(:key?, :id_sort)
+
         begin
-          if sort = criteria.options[:sort] || ( { _id: 1 } unless opts[:id_sort] == :none )
+          if sort = criteria.options[:sort] || ( { _id: 1 } unless opts.try(:fetch, :id_sort) == :none )
             @view = view.sort(Hash[sort.map{|k, v| [k, -1*v]}])
           end
           yield
@@ -793,6 +873,18 @@ module Mongoid
           end
         end
       end
+
+      # Process the raw documents retrieved for #first/#last.
+      #
+      # @return [ Array<Document> | Document ] The list of documents or a
+      #   single document.
+      def process_raw_docs(raw_docs, limit)
+        docs = raw_docs.map do |d|
+          Factory.from_db(klass, d, criteria)
+        end
+        docs = eager_load(docs)
+        limit ? docs : docs.first
+      end
     end
   end
 end

data/lib/mongoid/contextual/none.rb

@@ -105,13 +105,57 @@ module Mongoid
         @criteria, @klass = criteria, criteria.klass
       end
 
+      # Always returns nil.
+      #
+      # @example Get the first document in null context.
+      #   context.first
+      #
+      # @param [ Integer | Hash ] limit_or_opts The number of documents to
+      #   return, or a hash of options.
+      #
+      # @return [ nil ] Always nil.
+      def first(limit_or_opts = nil)
+        if !limit_or_opts.nil? && !limit_or_opts.is_a?(Hash)
+          []
+        end
+      end
+
       # Always returns nil.
       #
       # @example Get the last document in null context.
       #   context.last
       #
+      # @param [ Integer | Hash ] limit_or_opts The number of documents to
+      #   return, or a hash of options.
+      #
       # @return [ nil ] Always nil.
-      def last; nil; end
+      def last(limit_or_opts = nil)
+        if !limit_or_opts.nil? && !limit_or_opts.is_a?(Hash)
+          []
+        end
+      end
+
+      # Returns nil or empty array.
+      #
+      # @example Take a document in null context.
+      #   context.take
+      #
+      # @param [ Integer | nil ] limit The number of documents to take or nil.
+      #
+      # @return [ [] | nil ] Empty array or nil.
+      def take(limit = nil)
+        limit ? [] : nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Take a document in null context.
+      #   context.take!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def take!
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
 
       # Always returns zero.
       #

data/lib/mongoid/criteria/queryable/extensions/array.rb

@@ -116,6 +116,8 @@ module Mongoid
           # @param [ Proc ] block The block to execute on each value.
           #
           # @return [ Array ] the array.
+          #
+          # @deprecated
           def update_values(&block)
             replace(map(&block))
           end