mongoid 7.5.3 → 8.1.2

data/lib/mongoid/contextual/none.rb

@@ -40,7 +40,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)
         other.is_a?(None)
       end
@@ -50,7 +50,7 @@ module Mongoid
       # @example Get the distinct values in null context.
       #   context.distinct(:name)
       #
-      # @param [ String, Symbol ] _field The name of the field.
+      # @param [ String | Symbol ] _field The name of the field.
       #
       # @return [ Array ] An empty Array.
       def distinct(_field)
@@ -80,21 +80,54 @@ module Mongoid
       # @example Do any documents exist in the null 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: "...")
+      #
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
+      #
       # @return [ false ] Always false.
-      def exists?; false; end
+      def exists?(id_or_conditions = :none); false; end
 
       # Pluck the field values in null context.
       #
       # @example Get the values for null context.
       #   context.pluck(:name)
       #
-      # @param [ String, Symbol, Array ] args Field or fields to pluck.
+      # @param [ [ String | Symbol ]... ] *_fields Field(s) to pluck.
       #
       # @return [ Array ] An empty Array.
-      def pluck(*args)
+      def pluck(*_fields)
         []
       end
 
+      # Pick the field values in null context.
+      #
+      # @example Get the value for null context.
+      #   context.pick(:name)
+      #
+      # @param [ [ String | Symbol ]... ] *_fields Field(s) to pick.
+      #
+      # @return [ nil ] Always return nil.
+      def pick(*_fields)
+        nil
+      end
+
+      # Tally the field values in null context.
+      #
+      # @example Get the values for null context.
+      #   context.tally(:name)
+      #
+      # @param [ String | Symbol ] _field Field to tally.
+      #
+      # @return [ Hash ] An empty Hash.
+      def tally(_field)
+        {}
+      end
+
       # Create the new null context.
       #
       # @example Create the new context.
@@ -110,14 +143,21 @@ module Mongoid
       # @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.
+      # @param [ Integer ] limit The number of documents to return.
       #
-      # @return [ nil ] Always nil.
-      def first(limit_or_opts = nil)
-        if !limit_or_opts.nil? && !limit_or_opts.is_a?(Hash)
-          []
-        end
+      # @return [ [] | nil ] Empty array or nil.
+      def first(limit = nil)
+        [] unless limit.nil?
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the first document in null context.
+      #   context.first!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def first!
+        raise_document_not_found_error
       end
 
       # Always returns nil.
@@ -125,14 +165,21 @@ module Mongoid
       # @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.
+      # @param [ Integer ] limit The number of documents to return.
       #
-      # @return [ nil ] Always nil.
-      def last(limit_or_opts = nil)
-        if !limit_or_opts.nil? && !limit_or_opts.is_a?(Hash)
-          []
-        end
+      # @return [ [] | nil ] Empty array or nil.
+      def last(limit = nil)
+        [] unless limit.nil?
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the last document in null context.
+      #   context.last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def last!
+        raise_document_not_found_error
       end
 
       # Returns nil or empty array.
@@ -154,7 +201,127 @@ module Mongoid
       #
       # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
       def take!
-        raise Errors::DocumentNotFound.new(klass, nil, nil)
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the second document in null context.
+      #   context.second
+      #
+      # @return [ nil ] Always nil.
+      def second
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the second document in null context.
+      #   context.second!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def second!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the third document in null context.
+      #   context.third
+      #
+      # @return [ nil ] Always nil.
+      def third
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the third document in null context.
+      #   context.third!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def third!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the fourth document in null context.
+      #   context.fourth
+      #
+      # @return [ nil ] Always nil.
+      def fourth
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the fourth document in null context.
+      #   context.fourth!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def fourth!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the fifth document in null context.
+      #   context.fifth
+      #
+      # @return [ nil ] Always nil.
+      def fifth
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the fifth document in null context.
+      #   context.fifth!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def fifth!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the second to last document in null context.
+      #   context.second_to_last
+      #
+      # @return [ nil ] Always nil.
+      def second_to_last
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the second to last document in null context.
+      #   context.second_to_last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def second_to_last!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the third to last document in null context.
+      #   context.third_to_last
+      #
+      # @return [ nil ] Always nil.
+      def third_to_last
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the third to last document in null context.
+      #   context.third_to_last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def third_to_last!
+        raise_document_not_found_error
       end
 
       # Always returns zero.
@@ -170,6 +337,12 @@ module Mongoid
 
       alias :find_first :first
       alias :one :first
+
+      private
+
+      def raise_document_not_found_error
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
     end
   end
 end

data/lib/mongoid/contextual/queryable.rb

@@ -14,7 +14,7 @@ module Mongoid
       # @example Is the context empty?
       #   context.blank?
       #
-      # @return [ true, false ] If the context is empty.
+      # @return [ true | false ] If the context is empty.
       def blank?
         !exists?
       end

data/lib/mongoid/contextual.rb

@@ -30,11 +30,23 @@ module Mongoid
     # @example Get the context.
     #   criteria.context
     #
-    # @return [ Memory, Mongo ] The context.
+    # @return [ Memory | Mongo ] The context.
     def context
       @context ||= create_context
     end
 
+    # Instructs the context to schedule an asynchronous loading of documents
+    # specified by the criteria.
+    #
+    # Note that depending on the context and on the Mongoid configuration,
+    # documents can be loaded synchronously on the caller's thread.
+    #
+    # @return [ Criteria ] Returns self.
+    def load_async
+      context.load_async if context.respond_to?(:load_async)
+      self
+    end
+
     private
 
     # Create the context for the queries to execute. Will be memory for
@@ -45,7 +57,7 @@ module Mongoid
     # @example Create the context.
     #   contextual.create_context
     #
-    # @return [ Mongo, Memory ] The context.
+    # @return [ Mongo | Memory ] The context.
     def create_context
       return None.new(self) if empty_and_chainable?
       embedded ? Memory.new(self) : Mongo.new(self)

data/lib/mongoid/copyable.rb

@@ -10,7 +10,11 @@ module Mongoid
     # the exception of the document's id, and will reset all the
     # instance variables.
     #
-    # This clone also includes embedded documents.
+    # This clone also includes embedded documents. If there is an _id field in
+    # the embedded document, it will be maintained, unlike the root's _id.
+    #
+    # If cloning an embedded child, the embedded parent is not cloned and the
+    # embedded_in association is not set.
     #
     # @example Clone the document.
     #   document.clone
@@ -19,19 +23,42 @@ module Mongoid
     def clone
       # @note This next line is here to address #2704, even though having an
       # _id and id field in the document would cause problems with Mongoid
-      # elsewhere.
+      # elsewhere. Note this is only done on the root document as we want
+      # to maintain the same _id on the embedded documents.
       attrs = clone_document.except(*self.class.id_fields)
+      Copyable.clone_with_hash(self.class, attrs)
+    end
+    alias :dup :clone
+
+    private
+
+    # Create clone of a document of the given klass with the given attributes
+    # hash. This is used recursively so that embedded associations are cloned
+    # safely.
+    #
+    # @param klass [ Class ] The class of the document to create.
+    # @param attrs [ Hash ] The hash of the attributes.
+    #
+    # @return [ Document ] The new document.
+    def self.clone_with_hash(klass, attrs)
       dynamic_attrs = {}
-      _attribute_names = self.attribute_names
+      _attribute_names = klass.attribute_names
       attrs.reject! do |attr_name, value|
         unless _attribute_names.include?(attr_name)
           dynamic_attrs[attr_name] = value
           true
         end
       end
-      self.class.new(attrs).tap do |object|
+
+      Factory.build(klass, attrs).tap do |object|
         dynamic_attrs.each do |attr_name, value|
-          if object.respond_to?("#{attr_name}=")
+          assoc = object.embedded_relations[attr_name]
+          if assoc&.one? && Hash === value
+            object.send("#{attr_name}=", clone_with_hash(assoc.klass, value))
+          elsif assoc&.many? && Array === value
+            docs = value.map { |h| clone_with_hash(assoc.klass, h) }
+            object.send("#{attr_name}=", docs)
+          elsif object.respond_to?("#{attr_name}=")
             object.send("#{attr_name}=", value)
           else
             object.attributes[attr_name] = value
@@ -39,9 +66,6 @@ module Mongoid
         end
       end
     end
-    alias :dup :clone
-
-    private
 
     # Clone the document attributes
     #

data/lib/mongoid/criteria/findable.rb

@@ -10,18 +10,21 @@ module Mongoid
       #   criteria.execute_or_raise(id)
       #
       # @param [ Object ] ids The arguments passed.
-      # @param [ true, false ] multi Whether there arguments were a list.
+      # @param [ true | false ] multi Whether there arguments were a list.
       #
       # @raise [ Errors::DocumentNotFound ] If nothing returned.
       #
-      # @return [ Document, Array<Document> ] The document(s).
+      # @return [ Document | Array<Document> ] The document(s).
       def execute_or_raise(ids, multi)
         result = multiple_from_db(ids)
         check_for_missing_documents!(result, ids)
         multi ? result : result.first
       end
 
-      # Find the matchind document(s) in the criteria for the provided ids.
+      # Find the matching document(s) in the criteria for the provided id(s).
+      #
+      # @note Each argument can be an individual id, an array of ids or
+      #   a nested array. Each array will be flattened.
       #
       # @example Find by an id.
       #   criteria.find(BSON::ObjectId.new)
@@ -29,9 +32,9 @@ module Mongoid
       # @example Find by multiple ids.
       #   criteria.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
       #
-      # @param [ Array<BSON::ObjectId> ] args The ids to search for.
+      # @param [ [ Object | Array<Object> ]... ] *args The id(s) to find.
       #
-      # @return [ Array<Document>, Document ] The matching document(s).
+      # @return [ Document | Array<Document> ] The matching document(s).
       def find(*args)
         ids = args.__find_args__
         raise_invalid if ids.any?(&:nil?)

data/lib/mongoid/criteria/includable.rb

@@ -21,20 +21,17 @@ module Mongoid
       # @example Eager load the provided associations.
       #   Person.includes(:posts, :game)
       #
-      # @param [ Array<Symbol>, Array<Hash> ] relations The names of the associations to eager
-      #   load.
+      # @param [ [ Symbol | Hash ]... ] *relations The names of the association(s)
+      #   to eager load.
       #
       # @return [ Criteria ] The cloned criteria.
       def includes(*relations)
-        extract_includes_list(klass, relations)
+        extract_includes_list(klass, nil, relations)
         clone
       end
 
       # Get a list of criteria that are to be executed for eager loading.
       #
-      # @example Get the eager loading inclusions.
-      #   Person.includes(:game).inclusions
-      #
       # @return [ Array<Association> ] The inclusions.
       def inclusions
         @inclusions ||= []
@@ -42,9 +39,6 @@ module Mongoid
 
       # Set the inclusions for the criteria.
       #
-      # @example Set the inclusions.
-      #   criteria.inclusions = [ association ]
-      #
       # @param [ Array<Association> ] value The inclusions.
       #
       # @return [ Array<Association> ] The new inclusions.
@@ -56,30 +50,41 @@ module Mongoid
 
       # Add an inclusion definition to the list of inclusions for the criteria.
       #
-      # @example Add an inclusion.
-      #   criteria.add_inclusion(Person, :posts)
-      #
-      # @param [ Class, String, Symbol ] _klass The class or string/symbol of the class name.
-      # @param [ Symbol ] association The association.
-      #
-      # @raise [ Errors::InvalidIncludes ] If no association is found.
-      def add_inclusion(_klass, association)
-        inclusions.push(association) unless inclusions.include?(association)
+      # @param [ Association ] association The association.
+      # @param [ String ] parent The name of the association above this one in
+      #   the inclusion tree, if it is a nested inclusion.
+      def add_inclusion(association, parent = nil)
+        if assoc = inclusions.detect { |a| a == association }
+          assoc.parent_inclusions.push(parent) if parent
+        else
+          assoc = association.dup
+          assoc.parent_inclusions = []
+          assoc.parent_inclusions.push(parent) if parent
+          inclusions.push(assoc)
+        end
       end
 
-      def extract_includes_list(_parent_class, *relations_list)
+      # Iterate through the list of relations and create the inclusions list.
+      #
+      # @param [ Class | String | Symbol ] _parent_class The class from which the
+      #   association originates.
+      # @param [ String ] parent The name of the association above this one in
+      #   the inclusion tree, if it is a nested inclusion.
+      # @param [ [ Symbol | Hash | Array<Symbol | Hash> ]... ] *relations_list
+      #   The names of the association(s) to eager load.
+      def extract_includes_list(_parent_class, parent, *relations_list)
         relations_list.flatten.each do |relation_object|
           if relation_object.is_a?(Hash)
             relation_object.each do |relation, _includes|
               association = _parent_class.reflect_on_association(relation)
               raise Errors::InvalidIncludes.new(_klass, [ relation ]) unless association
-              add_inclusion(_parent_class, association)
-              extract_includes_list(association.klass, _includes)
+              add_inclusion(association, parent)
+              extract_includes_list(association.klass, association.name, _includes)
             end
           else
             association = _parent_class.reflect_on_association(relation_object)
             raise Errors::InvalidIncludes.new(_parent_class, [ relation_object ]) unless association
-            add_inclusion(_parent_class, association)
+            add_inclusion(association, parent)
           end
         end
       end

data/lib/mongoid/criteria/marshalable.rb

@@ -9,9 +9,12 @@ module Mongoid
       # @example Dump the criteria.
       #   Marshal.dump(criteria)
       #
+      # Note :mongo is written here for backwards compatibility with Mongoid 7
+      # and earlier.
+      #
       # @return [ Array<Object> ] The dumped data.
       def marshal_dump
-        data = [ klass, driver, inclusions, documents, strategy, negating ]
+        data = [ klass, :mongo, inclusions, documents, strategy, negating ]
         data.push(scoping_options).push(dump_hash(:selector)).push(dump_hash(:options))
       end
 
@@ -23,7 +26,12 @@ module Mongoid
       # @param [ Array ] data The raw data.
       def marshal_load(data)
         @scoping_options, raw_selector, raw_options = data.pop(3)
-        @klass, @driver, @inclusions, @documents, @strategy, @negating = data
+        @klass, driver, @inclusions, @documents, @strategy, @negating = data
+
+        if driver == :mongo1x
+          raise NotImplementedError, "Mongoid no longer supports marshalling with driver version 1.x."
+        end
+
         @selector = load_hash(Queryable::Selector, raw_selector)
         @options = load_hash(Queryable::Options, raw_options)
       end

data/lib/mongoid/criteria/permission.rb

@@ -54,7 +54,7 @@ module Mongoid
       # @api private
       #
       # @param [ Object ] criteria
-      # @return [ Boolean ] if should permit
+      # @return [ true | false ] if should permit
       def should_permit?(criteria)
         if criteria.respond_to?(:permitted?)
           return criteria.permitted?

data/lib/mongoid/criteria/queryable/aggregable.rb

@@ -20,7 +20,7 @@ module Mongoid
         # @example Is the aggregable aggregating?
         #   aggregable.aggregating?
         #
-        # @return [ true, false ] If the aggregable is aggregating.
+        # @return [ true | false ] If the aggregable is aggregating.
         def aggregating?
           !!@aggregating
         end
@@ -69,7 +69,7 @@ module Mongoid
         # @example Add an unwind to the pipeline.
         #   aggregable.unwind(:field)
         #
-        # @param [ String, Symbol ] field The name of the field to unwind.
+        # @param [ String | Symbol ] field The name of the field to unwind.
         #
         # @return [ Aggregable ] The aggregable.
         def unwind(field)

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

@@ -105,21 +105,7 @@ module Mongoid
           #
           # @return [ Hash ] The field/direction pair.
           def __sort_pair__
-            { first => last.to_direction }
-          end
-
-          # Update all the values in the hash with the provided block.
-          #
-          # @example Update the values in place.
-          #   [ 1, 2, 3 ].update_values(&:to_s)
-          #
-          # @param [ Proc ] block The block to execute on each value.
-          #
-          # @return [ Array ] the array.
-          #
-          # @deprecated
-          def update_values(&block)
-            replace(map(&block))
+            { first => Mongoid::Criteria::Translator.to_direction(last) }
           end
 
           private
@@ -147,7 +133,8 @@ module Mongoid
             #
             # @return [ Object ] The evolved object.
             def evolve(object)
-              if object.is_a?(::Array)
+              case object
+              when ::Array, ::Set
                 object.map { |obj| obj.class.evolve(obj) }
               else
                 object

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

@@ -12,18 +12,39 @@ module Mongoid
         module BigDecimal
           module ClassMethods
 
-            # Evolves the big decimal into a MongoDB friendly value - in this case
-            # a string.
+            # Evolves the big decimal into a MongoDB friendly value.
             #
             # @example Evolve the big decimal
             #   BigDecimal.evolve(decimal)
             #
             # @param [ BigDecimal ] object The object to convert.
             #
-            # @return [ String ] The big decimal as a string.
+            # @return [ Object ] The big decimal as a string, a Decimal128,
+            #   or the inputted object if it is uncastable.
             def evolve(object)
               __evolve__(object) do |obj|
-                obj ? obj.to_s : obj
+                return if obj.nil?
+                case obj
+                when ::BigDecimal
+                  if Mongoid.map_big_decimal_to_decimal128
+                    BSON::Decimal128.new(obj)
+                  else
+                    obj.to_s
+                  end
+                # Always return on string for backwards compatibility with querying
+                # string-backed BigDecimal fields.
+                when BSON::Decimal128, String then obj
+                else
+                  if obj.numeric?
+                    if Mongoid.map_big_decimal_to_decimal128
+                      BSON::Decimal128.new(object.to_s)
+                    else
+                      obj.to_s
+                    end
+                  else
+                    obj
+                  end
+                end
               end
             end
           end

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

@@ -17,10 +17,10 @@ module Mongoid
             #
             # @param [ Object ] object The object to evolve.
             #
-            # @return [ true, false ] The boolean value.
+            # @return [ true | false ] The boolean value.
             def evolve(object)
               __evolve__(object) do |obj|
-                obj.to_s =~ (/\A(true|t|yes|y|on|1|1.0)\z/i) ? true : false
+                mongoize(obj)
               end
             end
           end

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

@@ -45,7 +45,12 @@ module Mongoid
             #
             # @return [ Time ] The evolved date.
             def evolve(object)
-              object.__evolve_date__
+              res = begin
+                object.try(:__evolve_date__)
+              rescue ArgumentError
+                nil
+              end
+              res.nil? ? object : res
             end
           end
         end