mongoid 7.2.1 → 9.0.0

data/lib/mongoid/contextual/none.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
+
+require "mongoid/contextual/aggregable/none"
 
 module Mongoid
   module Contextual
+
+    # Context object used for performing bulk query and persistence
+    # operations on a null set. The method interface of this class
+    # is consistent with Mongoid::Contextual::Mongo.
     class None
       include Enumerable
+      include Aggregable::None
       include Queryable
 
       attr_reader :criteria, :klass
@@ -16,36 +23,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 +60,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!
+      #
+      # @raise [ 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!
+      #
+      # @raise [ 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!
+      #
+      # @raise [ 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!
+      #
+      # @raise [ 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!
       #
-      # @since 4.0.0
-      def last; nil; end
+      # @raise [ 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!
+      #
+      # @raise [ 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!
+      #
+      # @raise [ 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!
+      #
+      # @raise [ 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!
+      #
+      # @raise [ 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
       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,8 +1,11 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   module Contextual
+
+    # Mixin module which adds methods to Mongoid::Criteria that
+    # indicate the criteria query result will be an empty set.
     module Queryable
 
       # @attribute [r] collection The collection to query against.
@@ -15,9 +18,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,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require "mongoid/contextual/queryable"
 require "mongoid/contextual/mongo"
@@ -7,6 +7,9 @@ require "mongoid/contextual/memory"
 require "mongoid/contextual/none"
 
 module Mongoid
+
+  # Parent mixin module which adds aggregation (#sum, #avg, etc.) and
+  # atomic (#set, #unset, #push, etc.) behavior to Mongoid::Criteria.
   module Contextual
     extend Forwardable
 
@@ -31,13 +34,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 +61,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,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
 
@@ -11,7 +11,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,19 +24,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 [ Class ] klass The class of the document to create.
+    # @param [ Hash ] attrs 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
@@ -40,9 +67,6 @@ module Mongoid
         end
       end
     end
-    alias :dup :clone
-
-    private
 
     # Clone the document attributes
     #
@@ -50,8 +74,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)
@@ -67,8 +89,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)

data/lib/mongoid/criteria/findable.rb

@@ -1,8 +1,11 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 module Mongoid
   class Criteria
+
+    # Mixin module included in Mongoid::Criteria which adds the ability
+    # to find document by id.
     module Findable
 
       # Execute the criteria or raise an error if no documents found.
@@ -11,20 +14,22 @@ 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,
+      #   and therefore the return value should be an array.
       #
       # @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,15 +37,13 @@ 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.
-      #
-      # @return [ Array<Document>, Document ] The matching document(s).
+      # @param [ [ Object | Array<Object> ]... ] *args The id(s) to find.
       #
-      # @since 1.0.0
+      # @return [ Document | Array<Document> ] The matching document(s).
       def find(*args)
-        ids = args.__find_args__
+        ids = prepare_ids_for_find(args)
         raise_invalid if ids.any?(&:nil?)
-        for_ids(ids).execute_or_raise(ids, args.multi_arged?)
+        for_ids(ids).execute_or_raise(ids, multi_args?(args))
       end
 
       # Adds a criterion to the +Criteria+ that specifies an id that must be matched.
@@ -88,8 +91,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,13 +105,11 @@ 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
 
-      private def from_database_selector(ids)
+      def from_database_selector(ids)
         if ids.size > 1
           any_in(_id: ids)
         else
@@ -128,23 +127,54 @@ 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
 
+      # Convert args to the +#find+ method into a flat array of ids.
+      #
+      # @example Get the ids.
+      #   prepare_ids_for_find([ 1, [ 2, 3 ] ])
+      #
+      # @param [ Array<Object> ] args The arguments.
+      #
+      # @return [ Array ] The array of ids.
+      def prepare_ids_for_find(args)
+        args.flat_map do |arg|
+          case arg
+          when Array, Set
+            prepare_ids_for_find(arg)
+          when Range
+            arg.begin&.numeric? && arg.end&.numeric? ? arg.to_a : arg
+          else
+            arg
+          end
+        end.uniq(&:to_s)
+      end
+
+      # Indicates whether the given arguments array is a list of values.
+      # Used by the +find+ method to determine whether to return an array
+      # or single value.
+      #
+      # @example Are these arguments a list of values?
+      #   multi_args?([ 1, 2, 3 ]) #=> true
+      #
+      # @param [ Array ] args The arguments.
+      #
+      # @return [ true | false ] Whether the arguments are a list.
+      def multi_args?(args)
+        args.size > 1 || !args.first.is_a?(Hash) && args.first.resizable?
+      end
+
       # Convenience method of raising an invalid options error.
       #
       # @example Raise the error.
       #   criteria.raise_invalid
       #
       # @raise [ Errors::InvalidOptions ] The error.
-      #
-      # @since 2.0.0
       def raise_invalid
         raise Errors::InvalidFind.new
       end