mongoid 7.1.1 → 8.1.0

data/lib/mongoid/contextual/none.rb

@@ -1,14 +1,38 @@
 # frozen_string_literal: true
-# encoding: utf-8
+
+require "mongoid/contextual/aggregable/none"
 
 module Mongoid
   module Contextual
     class None
       include Enumerable
+      alias :old_sum :sum
+
+      include Aggregable::None
       include Queryable
 
       attr_reader :criteria, :klass
 
+      alias :new_sum :sum
+
+      # Get the sum in the null context.
+      #
+      # @example Get the sum of null context.
+      #     context.sum(_field)
+      #
+      # @param [ Symbol ] _field The field to sum.
+      #
+      # @return [ Integer | Symbol ] If Mongoid.broken_aggregables is
+      #   set to false, this will always be zero. Otherwise, it will return the
+      #   field name as a symbol.
+      def sum(_field = nil)
+        if Mongoid.broken_aggregables
+          old_sum(_field)
+        else
+          new_sum(_field)
+        end
+      end
+
       # Check if the context is equal to the other object.
       #
       # @example Check equality.
@@ -16,36 +40,32 @@ module Mongoid
       #
       # @param [ Array ] other The other array.
       #
-      # @return [ true, false ] If the objects are equal.
-      #
-      # @since 4.0.0
+      # @return [ true | false ] If the objects are equal.
       def ==(other)
         other.is_a?(None)
       end
 
-      # Allow distinct for null context.
+      # Get the distinct field values in null context.
       #
-      # @example Get the distinct values.
+      # @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 ] Empty Array
-      def distinct(field)
+      # @return [ Array ] An empty Array.
+      def distinct(_field)
         []
       end
 
       # Iterate over the null context. There are no documents to iterate over
       # in this case.
       #
-      # @example Iterate over the context.
+      # @example Iterate over the null context.
       #   context.each do |doc|
       #     puts doc.name
       #   end
       #
       # @return [ Enumerator ] The enumerator.
-      #
-      # @since 4.0.0
       def each
         if block_given?
           [].each { |doc| yield(doc) }
@@ -57,61 +77,272 @@ module Mongoid
 
       # Do any documents exist for the context.
       #
-      # @example Do any documents exist for the context.
+      # @example Do any documents exist in the null 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(...))
       #
-      # @since 4.0.0
-      def exists?; false; end
-
+      # @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?(id_or_conditions = :none); false; end
 
-      # Allow pluck for null context.
+      # Pluck the field values in null context.
       #
-      # @example Allow pluck for 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 ] Emtpy Array
-      def pluck(*args)
+      # @return [ Array ] An empty Array.
+      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.
       #   Null.new(criteria)
       #
       # @param [ Criteria ] criteria The criteria.
-      #
-      # @since 4.0.0
       def initialize(criteria)
         @criteria, @klass = criteria, criteria.klass
       end
 
       # Always returns nil.
       #
-      # @example Get the last document.
+      # @example Get the first document in null context.
+      #   context.first
+      #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @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.
+      #
+      # @example Get the last document in null context.
       #   context.last
       #
+      # @param [ Integer ] limit The number of documents to return.
+      #
+      # @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.
+      #
+      # @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_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.
       #
-      # @since 4.0.0
-      def last; nil; end
+      # @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.
       #
-      # @example Get the length of matching documents.
+      # @example Get the length of null context.
       #   context.length
       #
       # @return [ Integer ] Always zero.
-      #
-      # @since 4.0.0
       def length
-        entries.length
+        Mongoid.broken_aggregables ? 0 : entries.length
       end
       alias :size :length
+
+      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

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Contextual
@@ -15,9 +14,7 @@ module Mongoid
       # @example Is the context empty?
       #   context.blank?
       #
-      # @return [ true, false ] If the context is empty.
-      #
-      # @since 3.0.0
+      # @return [ true | false ] If the context is empty.
       def blank?
         !exists?
       end

data/lib/mongoid/contextual.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require "mongoid/contextual/queryable"
 require "mongoid/contextual/mongo"
@@ -31,13 +30,23 @@ module Mongoid
     # @example Get the context.
     #   criteria.context
     #
-    # @return [ Memory, Mongo ] The context.
-    #
-    # @since 3.0.0
+    # @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
@@ -48,9 +57,7 @@ module Mongoid
     # @example Create the context.
     #   contextual.create_context
     #
-    # @return [ Mongo, Memory ] The context.
-    #
-    # @since 3.0.0
+    # @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

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
 
@@ -11,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
@@ -20,15 +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.
-      attrs = clone_document.except("_id", "id")
+      # 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 = klass.attribute_names
       attrs.reject! do |attr_name, value|
-        dynamic_attrs.merge!(attr_name => value) unless self.attribute_names.include?(attr_name)
+        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
@@ -36,9 +66,6 @@ module Mongoid
         end
       end
     end
-    alias :dup :clone
-
-    private
 
     # Clone the document attributes
     #
@@ -46,8 +73,6 @@ module Mongoid
     #
     # @example clone document
     #   model.clone_document
-    #
-    # @since 3.0.22
     def clone_document
       attrs = as_attributes.__deep_copy__
       process_localized_attributes(self, attrs)
@@ -63,8 +88,6 @@ module Mongoid
     #   model.process_localized_attributes(attributes)
     #
     # @param [ Hash ] attrs The attributes.
-    #
-    # @since 3.0.20
     def process_localized_attributes(klass, attrs)
       klass.localized_fields.keys.each do |name|
         if value = attrs.delete(name)
@@ -76,8 +99,8 @@ module Mongoid
 
         if association.is_a?(Association::Embedded::EmbedsMany)
           attrs[association.key].each do |attr|
-            embedded_klass = if type = attr['_type']
-              type.constantize
+            embedded_klass = if type = attr[self.class.discriminator_key]
+              association.relation_class.get_discriminator_mapping(type) || association.relation_class
             else
               association.relation_class
             end

data/lib/mongoid/criteria/findable.rb

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   class Criteria
@@ -11,20 +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).
-      #
-      # @since 2.0.0
+      # @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)
@@ -32,11 +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).
-      #
-      # @since 1.0.0
+      # @return [ Document | Array<Document> ] The matching document(s).
       def find(*args)
         ids = args.__find_args__
         raise_invalid if ids.any?(&:nil?)
@@ -88,8 +86,6 @@ module Mongoid
       #   criteria.id_finder
       #
       # @return [ Symbol ] The name of the finder method.
-      #
-      # @since 3.1.0
       def id_finder
         @id_finder ||= extract_id ? :all_of : :where
       end
@@ -104,8 +100,6 @@ module Mongoid
       # @param [ Array<Object> ] ids The ids to fetch with.
       #
       # @return [ Array<Document> ] The matching documents.
-      #
-      # @since 3.0.0
       def from_database(ids)
         from_database_selector(ids).entries
       end
@@ -128,11 +122,9 @@ module Mongoid
       # @param [ Array<Object> ] ids The ids to convert.
       #
       # @return [ Array<Object> ] The converted ids.
-      #
-      # @since 3.0.0
       def mongoize_ids(ids)
         ids.map do |id|
-          id = id[:id] if id.respond_to?(:keys) && id[:id]
+          id = id[:_id] if id.respond_to?(:keys) && id[:_id]
           klass.fields["_id"].mongoize(id)
         end
       end
@@ -143,8 +135,6 @@ module Mongoid
       #   criteria.raise_invalid
       #
       # @raise [ Errors::InvalidOptions ] The error.
-      #
-      # @since 2.0.0
       def raise_invalid
         raise Errors::InvalidFind.new
       end