mongoid 7.2.1 → 7.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb2c430462ea474d889d41fa20a7011b5ddfeeac215cddc762c2e2a4324e8ef9
-  data.tar.gz: 002a48e7013981c8c12f45edca4f5c9a5c75c9b99ac5f2fd46422532871ae775
+  metadata.gz: 408fcc1f85dce0c9a16140dda363526896fe1fb37f627e33f15ef6d1a2628de0
+  data.tar.gz: '084168385d0912909c5292100334c8eb7edf162d72bcd1cd51673fd8140013ca'
 SHA512:
-  metadata.gz: 6985ec8a658d859e3a8f863eca20326d11aba2249488f10cff0bb6c01c8a4de759ab6726b1573e7e6a845ccf5b72213b8fe0374d699761e13608121216bafe98
-  data.tar.gz: fb681e64b86e56203d0029452b71f197bcadfb86b56ccadd514edc6bac416c68490ed708db5a09bc84cf638a43fb359d6ec977f31ca226429c0ca99de0af3120
+  metadata.gz: 193c335677afc72c56eebc7d64a0167cb4c9112e7b0a81baa39d6433a7c8b04d1a456e451777823c5678219bd73ad46198c8bd650e0cfb89b1ee87e77d4b62d4
+  data.tar.gz: b994ad71c11e4c9f94074fc082c91ffc479146bb0a9af87b28a4c7fa1bc338f737cb902d4098d50241ffb62cf9e6ba1deb2cdd3ffb951e1afa09cf3c02450e2c

data/README.md

@@ -19,7 +19,7 @@ Compatibility
 
 Mongoid supports and is tested against:
 
-- MRI 2.3-2.7
+- MRI 2.3-3.0
 - JRuby 9.2
 - MongoDB server 2.6-4.4
 

data/Rakefile

@@ -66,6 +66,22 @@ task :ci do
   spec_organizer.run
 end
 
+task :bucket, %i(buckets) do |task, args|
+  buckets = args[:buckets]
+  buckets = if buckets.nil? || buckets.empty?
+    [nil]
+  else
+    buckets.split(':').map do |bucket|
+      if bucket.empty?
+        nil
+      else
+        bucket.to_sym
+      end
+    end
+  end
+  spec_organizer.run_buckets(*buckets)
+end
+
 task :default => :spec
 
 desc "Generate all documentation"

data/lib/config/locales/en.yml

@@ -578,9 +578,9 @@ en:
           resolution: "Try persisting the document with valid data or remove
             the validations."
         delete_restriction:
-          message: "Cannot delete %{document} because of dependent '%{relation}'."
+          message: "Cannot destroy %{document} because of dependent '%{relation}'."
           summary: "When defining '%{relation}' with a :dependent => :restrict_with_error,
-            Mongoid will raise an error when attempting to delete the
+            Mongoid will raise an error when attempting to destroy the
             %{document} when the child '%{relation}' still has documents in it."
           resolution: "Don't attempt to delete the parent %{document} when
             it has children, or change the dependent option on the association."

data/lib/mongoid/association/accessors.rb

@@ -121,6 +121,9 @@ module Mongoid
       # (embedded) association with the given key, or nil if no projection
       # is to be performed.
       #
+      # Also returns nil if exclusionary projection was requested but it does
+      # not exclude the field of the association.
+      #
       # For example, if __selected_fields is {'a' => 1, 'b.c' => 2, 'b.c.f' => 3},
       # and assoc_key is 'b', return value would be {'c' => 2, 'c.f' => 3}.
       #
@@ -132,6 +135,15 @@ module Mongoid
       def _mongoid_filter_selected_fields(assoc_key)
         return nil unless __selected_fields
 
+        # If the list of fields was specified using #without instead of #only
+        # and the provided list does not include the association, any of its
+        # fields should be allowed.
+        if __selected_fields.values.all? { |v| v == 0 } &&
+          __selected_fields.keys.none? { |k| k.split('.', 2).first == assoc_key }
+        then
+          return nil
+        end
+
         projecting_assoc = false
 
         filtered = {}
@@ -300,7 +312,7 @@ module Mongoid
         ids_method = "#{association.name.to_s.singularize}_ids"
         association.inverse_class.tap do |klass|
           klass.re_define_method(ids_method) do
-            send(association.name).only(:id).map(&:id)
+            send(association.name).only(:_id).map(&:_id)
           end
         end
       end

data/lib/mongoid/association/constrainable.rb

@@ -36,7 +36,7 @@ module Mongoid
 
       def convert_polymorphic(object)
         if object.is_a?(Mongoid::Document)
-          object.id
+          object._id
         else
           BSON::ObjectId.mongoize(object)
         end

data/lib/mongoid/association/depending.rb

@@ -78,13 +78,13 @@ module Mongoid
       # the appropriate strategy to perform the operation.
       #
       # @example Execute cascades.
-      #   document.apply_delete_dependencies!
+      #   document.apply_destroy_dependencies!
       #
       # @since 2.0.0.rc.1
-      def apply_delete_dependencies!
+      def apply_destroy_dependencies!
         self.class._all_dependents.each do |association|
-          if association.try(:dependent)
-            send("_dependent_#{association.dependent}!", association)
+          if dependent = association.try(:dependent)
+            send("_dependent_#{dependent}!", association)
           end
         end
       end

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

@@ -329,7 +329,7 @@ module Mongoid
             self.path = doc.atomic_path unless path
             execute_callback :before_remove, doc
             unless _assigning?
-              doc.apply_delete_dependencies!
+              doc.apply_destroy_dependencies!
               doc.run_before_callbacks(:destroy) if method == :destroy
             end
             _target.delete_one(doc)

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

@@ -26,7 +26,7 @@ module Mongoid
             :autobuild,
             :cyclic,
             :polymorphic,
-            :touch
+            :touch,
         ].freeze
 
         # The complete list of valid options for this association, including

data/lib/mongoid/association/embedded/embeds_many/proxy.rb

@@ -83,8 +83,15 @@ module Mongoid
 
           alias :new :build
 
-          # Clear the association. Will delete the documents from the db if they are
-          # already persisted.
+          # Clear the association. Will delete the documents from the db
+          # if they are already persisted.
+          #
+          # If the host document is not persisted but its _id matches a
+          # persisted document, calling #clear on an association will remove
+          # the association's documents from the database even though the
+          # set of documents in the application (as loaded in the host)
+          # is different from what is in the database, and the host may
+          # not contain any persisted documents in the association either.
           #
           # @example Clear the association.
           #   person.addresses.clear
@@ -332,7 +339,7 @@ module Mongoid
           private
 
           def object_already_related?(document)
-            _target.any? { |existing| existing.id && existing === document }
+            _target.any? { |existing| existing._id && existing === document }
           end
 
           # Appends the document to the target array, updating the index on the

data/lib/mongoid/association/nested/many.rb

@@ -181,7 +181,7 @@ module Mongoid
           first = existing.first
           converted = first ? convert_id(first.class, id) : id
 
-          if existing.where(id: converted).exists?
+          if existing.where(_id: converted).exists?
             # document exists in association
             doc = existing.find(converted)
             if destroyable?(attrs)

data/lib/mongoid/association/nested/one.rb

@@ -71,7 +71,8 @@ module Mongoid
         #
         # @since 2.0.0
         def acceptable_id?
-          id = convert_id(existing.class, attributes[:id])
+          id = association.klass.extract_id_field(attributes)
+          id = convert_id(existing.class, id)
           existing._id == id || id.nil? || (existing._id != id && update_only?)
         end
 
@@ -84,7 +85,8 @@ module Mongoid
         #
         # @since 2.0.0
         def delete?
-          destroyable? && !attributes[:id].nil?
+          id = association.klass.extract_id_field(attributes)
+          destroyable? && !id.nil?
         end
 
         # Can the existing association potentially be destroyed?

data/lib/mongoid/association/proxy.rb

@@ -16,7 +16,7 @@ module Mongoid
       # We undefine most methods to get them sent through to the target.
       instance_methods.each do |method|
         undef_method(method) unless
-          method =~ /\A(__.*|send|object_id|equal\?|respond_to\?|tap|public_send|extend_proxy|extend_proxies)\z/
+          method =~ /\A(?:__.*|send|object_id|equal\?|respond_to\?|respond_to_missing\?|tap|public_send|extend_proxy|extend_proxies)\z/
       end
 
       include Threaded::Lifecycle
@@ -137,6 +137,11 @@ module Mongoid
         _target.send(name, *args, &block)
       end
 
+      # @api private
+      def respond_to_missing?(name, *args)
+        _target.respond_to?(name, *args)
+      end
+
       # When the base document illegally references an embedded document this
       # error will get raised.
       #

data/lib/mongoid/association/referenced/auto_save.rb

@@ -63,8 +63,8 @@ module Mongoid
                 self.before_callback_halted = false
               else
                 __autosaving__ do
-                  if relation = ivar(association.name)
-                    Array(relation).each do |doc|
+                  if assoc_value = ivar(association.name)
+                    Array(assoc_value).each do |doc|
                       doc.with(persistence_context) do |d|
                         d.save
                       end

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

@@ -5,544 +5,542 @@ module Mongoid
   module Association
     module Referenced
       class HasMany
-        module Targets
-
-          # This class is the wrapper for all referenced associations that have a
-          # target that can be a criteria or array of _loaded documents. This
-          # handles both cases or a combination of the two.
-          class Enumerable
-            extend Forwardable
-            include ::Enumerable
-
-            # The three main instance variables are collections of documents.
-            #
-            # @attribute [rw] _added Documents that have been appended.
-            # @attribute [rw] _loaded Persisted documents that have been _loaded.
-            # @attribute [rw] _unloaded A criteria representing persisted docs.
-            attr_accessor :_added, :_loaded, :_unloaded
-
-            def_delegators [], :is_a?, :kind_of?
-
-            # Check if the enumerable is equal to the other object.
-            #
-            # @example Check equality.
-            #   enumerable == []
-            #
-            # @param [ Enumerable ] other The other enumerable.
-            #
-            # @return [ true, false ] If the objects are equal.
-            #
-            # @since 2.1.0
-            def ==(other)
-              return false unless other.respond_to?(:entries)
-              entries == other.entries
-            end
 
-            # Check equality of the enumerable against the provided object for case
-            # statements.
-            #
-            # @example Check case equality.
-            #   enumerable === Array
-            #
-            # @param [ Object ] other The object to check.
-            #
-            # @return [ true, false ] If the objects are equal in a case.
-            #
-            # @since 3.1.4
-            def ===(other)
-              other.class == Class ? (Array == other || Enumerable == other) : self == other
-            end
+        # This class is the wrapper for all referenced associations that have a
+        # target that can be a criteria or array of _loaded documents. This
+        # handles both cases or a combination of the two.
+        class Enumerable
+          extend Forwardable
+          include ::Enumerable
+
+          # The three main instance variables are collections of documents.
+          #
+          # @attribute [rw] _added Documents that have been appended.
+          # @attribute [rw] _loaded Persisted documents that have been _loaded.
+          # @attribute [rw] _unloaded A criteria representing persisted docs.
+          attr_accessor :_added, :_loaded, :_unloaded
+
+          def_delegators [], :is_a?, :kind_of?
+
+          # Check if the enumerable is equal to the other object.
+          #
+          # @example Check equality.
+          #   enumerable == []
+          #
+          # @param [ Enumerable ] other The other enumerable.
+          #
+          # @return [ true, false ] If the objects are equal.
+          #
+          # @since 2.1.0
+          def ==(other)
+            return false unless other.respond_to?(:entries)
+            entries == other.entries
+          end
 
-            # Append a document to the enumerable.
-            #
-            # @example Append the document.
-            #   enumerable << document
-            #
-            # @param [ Document ] document The document to append.
-            #
-            # @return [ Document ] The document.
-            #
-            # @since 2.1.0
-            def <<(document)
-              _added[document._id] = document
-              self
-            end
+          # Check equality of the enumerable against the provided object for case
+          # statements.
+          #
+          # @example Check case equality.
+          #   enumerable === Array
+          #
+          # @param [ Object ] other The object to check.
+          #
+          # @return [ true, false ] If the objects are equal in a case.
+          #
+          # @since 3.1.4
+          def ===(other)
+            other.class == Class ? (Array == other || Enumerable == other) : self == other
+          end
 
-            alias :push :<<
-
-            # Clears out all the documents in this enumerable. If passed a block it
-            # will yield to each document that is in memory.
-            #
-            # @example Clear out the enumerable.
-            #   enumerable.clear
-            #
-            # @example Clear out the enumerable with a block.
-            #   enumerable.clear do |doc|
-            #     doc.unbind
-            #   end
-            #
-            # @return [ Array<Document> ] The cleared out _added docs.
-            #
-            # @since 2.1.0
-            def clear
-              if block_given?
-                in_memory { |doc| yield(doc) }
-              end
-              _loaded.clear and _added.clear
-            end
+          # Append a document to the enumerable.
+          #
+          # @example Append the document.
+          #   enumerable << document
+          #
+          # @param [ Document ] document The document to append.
+          #
+          # @return [ Document ] The document.
+          #
+          # @since 2.1.0
+          def <<(document)
+            _added[document._id] = document
+            self
+          end
 
-            # Clones each document in the enumerable.
-            #
-            # @note This loads all documents into memory.
-            #
-            # @example Clone the enumerable.
-            #   enumerable.clone
-            #
-            # @return [ Array<Document> ] An array clone of the enumerable.
-            #
-            # @since 2.1.6
-            def clone
-              collect { |doc| doc.clone }
+          alias :push :<<
+
+          # Clears out all the documents in this enumerable. If passed a block it
+          # will yield to each document that is in memory.
+          #
+          # @example Clear out the enumerable.
+          #   enumerable.clear
+          #
+          # @example Clear out the enumerable with a block.
+          #   enumerable.clear do |doc|
+          #     doc.unbind
+          #   end
+          #
+          # @return [ Array<Document> ] The cleared out _added docs.
+          #
+          # @since 2.1.0
+          def clear
+            if block_given?
+              in_memory { |doc| yield(doc) }
             end
+            _loaded.clear and _added.clear
+          end
+
+          # Clones each document in the enumerable.
+          #
+          # @note This loads all documents into memory.
+          #
+          # @example Clone the enumerable.
+          #   enumerable.clone
+          #
+          # @return [ Array<Document> ] An array clone of the enumerable.
+          #
+          # @since 2.1.6
+          def clone
+            collect { |doc| doc.clone }
+          end
 
-            # Delete the supplied document from the enumerable.
-            #
-            # @example Delete the document.
-            #   enumerable.delete(document)
-            #
-            # @param [ Document ] document The document to delete.
-            #
-            # @return [ Document ] The deleted document.
-            #
-            # @since 2.1.0
-            def delete(document)
-              doc = (_loaded.delete(document._id) || _added.delete(document._id))
-              unless doc
-                if _unloaded && _unloaded.where(_id: document._id).exists?
-                  yield(document) if block_given?
-                  return document
-                end
+          # Delete the supplied document from the enumerable.
+          #
+          # @example Delete the document.
+          #   enumerable.delete(document)
+          #
+          # @param [ Document ] document The document to delete.
+          #
+          # @return [ Document ] The deleted document.
+          #
+          # @since 2.1.0
+          def delete(document)
+            doc = (_loaded.delete(document._id) || _added.delete(document._id))
+            unless doc
+              if _unloaded && _unloaded.where(_id: document._id).exists?
+                yield(document) if block_given?
+                return document
               end
-              yield(doc) if block_given?
-              doc
             end
+            yield(doc) if block_given?
+            doc
+          end
 
-            # Deletes every document in the enumerable for where the block returns
-            # true.
-            #
-            # @note This operation loads all documents from the database.
-            #
-            # @example Delete all matching documents.
-            #   enumerable.delete_if do |doc|
-            #     dod._id == _id
-            #   end
-            #
-            # @return [ Array<Document> ] The remaining docs.
-            #
-            # @since 2.1.0
-            def delete_if(&block)
-              load_all!
-              deleted = in_memory.select(&block)
-              deleted.each do |doc|
-                _loaded.delete(doc._id)
-                _added.delete(doc._id)
-              end
-              self
+          # Deletes every document in the enumerable for where the block returns
+          # true.
+          #
+          # @note This operation loads all documents from the database.
+          #
+          # @example Delete all matching documents.
+          #   enumerable.delete_if do |doc|
+          #     dod._id == _id
+          #   end
+          #
+          # @return [ Array<Document> ] The remaining docs.
+          #
+          # @since 2.1.0
+          def delete_if(&block)
+            load_all!
+            deleted = in_memory.select(&block)
+            deleted.each do |doc|
+              _loaded.delete(doc._id)
+              _added.delete(doc._id)
             end
+            self
+          end
 
-            # Iterating over this enumerable has to handle a few different
-            # scenarios.
-            #
-            # If the enumerable has its criteria _loaded into memory then it yields
-            # to all the _loaded docs and all the _added docs.
-            #
-            # If the enumerable has not _loaded the criteria then it iterates over
-            # the cursor while loading the documents and then iterates over the
-            # _added docs.
-            #
-            # If no block is passed then it returns an enumerator containing all
-            # docs.
-            #
-            # @example Iterate over the enumerable.
-            #   enumerable.each do |doc|
-            #     puts doc
-            #   end
-            #
-            # @example return an enumerator containing all the docs
-            #
-            #   a = enumerable.each
-            #
-            # @return [ true ] That the enumerable is now _loaded.
-            #
-            # @since 2.1.0
-            def each
-              unless block_given?
-                return to_enum
-              end
-              if _loaded?
-                _loaded.each_pair do |id, doc|
-                  document = _added.delete(doc._id) || doc
-                  set_base(document)
-                  yield(document)
-                end
-              else
-                unloaded_documents.each do |doc|
-                  document = _added.delete(doc._id) || _loaded.delete(doc._id) || doc
-                  _loaded[document._id] = document
-                  set_base(document)
-                  yield(document)
-                end
+          # Iterating over this enumerable has to handle a few different
+          # scenarios.
+          #
+          # If the enumerable has its criteria _loaded into memory then it yields
+          # to all the _loaded docs and all the _added docs.
+          #
+          # If the enumerable has not _loaded the criteria then it iterates over
+          # the cursor while loading the documents and then iterates over the
+          # _added docs.
+          #
+          # If no block is passed then it returns an enumerator containing all
+          # docs.
+          #
+          # @example Iterate over the enumerable.
+          #   enumerable.each do |doc|
+          #     puts doc
+          #   end
+          #
+          # @example return an enumerator containing all the docs
+          #
+          #   a = enumerable.each
+          #
+          # @return [ true ] That the enumerable is now _loaded.
+          #
+          # @since 2.1.0
+          def each
+            unless block_given?
+              return to_enum
+            end
+            if _loaded?
+              _loaded.each_pair do |id, doc|
+                document = _added.delete(doc._id) || doc
+                set_base(document)
+                yield(document)
               end
-              _added.each_pair do |id, doc|
-                yield(doc)
+            else
+              unloaded_documents.each do |doc|
+                document = _added.delete(doc._id) || _loaded.delete(doc._id) || doc
+                _loaded[document._id] = document
+                set_base(document)
+                yield(document)
               end
-              @executed = true
             end
-
-            # Is the enumerable empty? Will determine if the count is zero based on
-            # whether or not it is _loaded.
-            #
-            # @example Is the enumerable empty?
-            #   enumerable.empty?
-            #
-            # @return [ true, false ] If the enumerable is empty.
-            #
-            # @since 2.1.0
-            def empty?
-              if _loaded?
-                in_memory.count == 0
-              else
-                _unloaded.count + _added.count == 0
-              end
+            _added.each_pair do |id, doc|
+              yield(doc)
             end
+            @executed = true
+          end
 
-            # Returns whether the association has any documents, optionally
-            # subject to the provided filters.
-            #
-            # This method returns true if the association has any persisted
-            # documents and if it has any not yet persisted documents.
-            #
-            # If the association is already loaded, this method inspects the
-            # loaded documents and does not query the database. If the
-            # association is not loaded, the argument-less and block-less
-            # version does not load the association; the other versions
-            # (that delegate to Enumerable) may or may not load the association
-            # completely depending on whether it is iterated to completion.
-            #
-            # This method can take a parameter and a block. The behavior with
-            # either the paramater or the block is delegated to the standard
-            # library Enumerable module.
-            #
-            # Note that when Enumerable's any? method is invoked with both
-            # a block and a pattern, it only uses the pattern.
-            #
-            # @param [ Object ] condition The condition that documents
-            #   must satisfy. See Enumerable documentation for details.
-            #
-            # @return [ true, false ] If the association has any documents.
-            def any?(*args)
-              return super if args.any? || block_given?
-
-              if _loaded?
-                in_memory.length > 0
-              else
-                _unloaded.exists? || _added.length > 0
-              end
+          # Is the enumerable empty? Will determine if the count is zero based on
+          # whether or not it is _loaded.
+          #
+          # @example Is the enumerable empty?
+          #   enumerable.empty?
+          #
+          # @return [ true, false ] If the enumerable is empty.
+          #
+          # @since 2.1.0
+          def empty?
+            if _loaded?
+              in_memory.count == 0
+            else
+              _unloaded.count + _added.count == 0
             end
+          end
 
-            # Get the first document in the enumerable. Will check the persisted
-            # documents first. Does not load the entire enumerable.
-            #
-            # @example Get the first document.
-            #   enumerable.first
-            #
-            # @note Automatically adding a sort on _id when no other sort is
-            #   defined on the criteria has the potential to cause bad performance issues.
-            #   If you experience unexpected poor performance when using #first or #last,
-            #   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.
-            #
-            # @option opts [ :none ] :id_sort Don't apply a sort on _id.
-            #
-            # @return [ Document ] The first document found.
-            #
-            # @since 2.1.0
-            def first(opts = {})
-              _loaded.try(:values).try(:first) ||
-                  _added[(ul = _unloaded.try(:first, opts)).try(:id)] ||
-                  ul ||
-                  _added.values.try(:first)
+          # Returns whether the association has any documents, optionally
+          # subject to the provided filters.
+          #
+          # This method returns true if the association has any persisted
+          # documents and if it has any not yet persisted documents.
+          #
+          # If the association is already loaded, this method inspects the
+          # loaded documents and does not query the database. If the
+          # association is not loaded, the argument-less and block-less
+          # version does not load the association; the other versions
+          # (that delegate to Enumerable) may or may not load the association
+          # completely depending on whether it is iterated to completion.
+          #
+          # This method can take a parameter and a block. The behavior with
+          # either the paramater or the block is delegated to the standard
+          # library Enumerable module.
+          #
+          # Note that when Enumerable's any? method is invoked with both
+          # a block and a pattern, it only uses the pattern.
+          #
+          # @param [ Object ] condition The condition that documents
+          #   must satisfy. See Enumerable documentation for details.
+          #
+          # @return [ true, false ] If the association has any documents.
+          def any?(*args)
+            return super if args.any? || block_given?
+
+            if _loaded?
+              in_memory.length > 0
+            else
+              _unloaded.exists? || _added.length > 0
             end
+          end
 
-            # Initialize the new enumerable either with a criteria or an array.
-            #
-            # @example Initialize the enumerable with a criteria.
-            #   Enumberable.new(Post.where(:person_id => id))
-            #
-            # @example Initialize the enumerable with an array.
-            #   Enumerable.new([ post ])
-            #
-            # @param [ Criteria, Array<Document> ] target The wrapped object.
-            #
-            # @since 2.1.0
-            def initialize(target, base = nil, association = nil)
-              @_base = base
-              @_association = association
-              if target.is_a?(Criteria)
-                @_added, @executed, @_loaded, @_unloaded = {}, false, {}, target
-              else
-                @_added, @executed = {}, true
-                @_loaded = target.inject({}) do |_target, doc|
-                  _target[doc._id] = doc if doc
-                  _target
-                end
+          # Get the first document in the enumerable. Will check the persisted
+          # documents first. Does not load the entire enumerable.
+          #
+          # @example Get the first document.
+          #   enumerable.first
+          #
+          # @note Automatically adding a sort on _id when no other sort is
+          #   defined on the criteria has the potential to cause bad performance issues.
+          #   If you experience unexpected poor performance when using #first or #last,
+          #   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.
+          #
+          # @option opts [ :none ] :id_sort Don't apply a sort on _id.
+          #
+          # @return [ Document ] The first document found.
+          #
+          # @since 2.1.0
+          def first(opts = {})
+            _loaded.try(:values).try(:first) ||
+                _added[(ul = _unloaded.try(:first, opts)).try(:_id)] ||
+                ul ||
+                _added.values.try(:first)
+          end
+
+          # Initialize the new enumerable either with a criteria or an array.
+          #
+          # @example Initialize the enumerable with a criteria.
+          #   Enumberable.new(Post.where(:person_id => id))
+          #
+          # @example Initialize the enumerable with an array.
+          #   Enumerable.new([ post ])
+          #
+          # @param [ Criteria, Array<Document> ] target The wrapped object.
+          #
+          # @since 2.1.0
+          def initialize(target, base = nil, association = nil)
+            @_base = base
+            @_association = association
+            if target.is_a?(Criteria)
+              @_added, @executed, @_loaded, @_unloaded = {}, false, {}, target
+            else
+              @_added, @executed = {}, true
+              @_loaded = target.inject({}) do |_target, doc|
+                _target[doc._id] = doc if doc
+                _target
               end
             end
+          end
 
-            # Does the target include the provided document?
-            #
-            # @example Does the target include the document?
-            #   enumerable.include?(document)
-            #
-            # @param [ Document ] doc The document to check.
-            #
-            # @return [ true, false ] If the document is in the target.
-            #
-            # @since 3.0.0
-            def include?(doc)
-              return super unless _unloaded
-              _unloaded.where(_id: doc._id).exists? || _added.has_key?(doc._id)
-            end
+          # Does the target include the provided document?
+          #
+          # @example Does the target include the document?
+          #   enumerable.include?(document)
+          #
+          # @param [ Document ] doc The document to check.
+          #
+          # @return [ true, false ] If the document is in the target.
+          #
+          # @since 3.0.0
+          def include?(doc)
+            return super unless _unloaded
+            _unloaded.where(_id: doc._id).exists? || _added.has_key?(doc._id)
+          end
 
-            # Inspection will just inspect the entries for nice array-style
-            # printing.
-            #
-            # @example Inspect the enumerable.
-            #   enumerable.inspect
-            #
-            # @return [ String ] The inspected enum.
-            #
-            # @since 2.1.0
-            def inspect
-              entries.inspect
-            end
+          # Inspection will just inspect the entries for nice array-style
+          # printing.
+          #
+          # @example Inspect the enumerable.
+          #   enumerable.inspect
+          #
+          # @return [ String ] The inspected enum.
+          #
+          # @since 2.1.0
+          def inspect
+            entries.inspect
+          end
 
-            # Return all the documents in the enumerable that have been _loaded or
-            # _added.
-            #
-            # @note When passed a block it yields to each document.
-            #
-            # @example Get the in memory docs.
-            #   enumerable.in_memory
-            #
-            # @return [ Array<Document> ] The in memory docs.
-            #
-            # @since 2.1.0
-            def in_memory
-              docs = (_loaded.values + _added.values)
-              docs.each do |doc|
-                yield(doc) if block_given?
-              end
+          # Return all the documents in the enumerable that have been _loaded or
+          # _added.
+          #
+          # @note When passed a block it yields to each document.
+          #
+          # @example Get the in memory docs.
+          #   enumerable.in_memory
+          #
+          # @return [ Array<Document> ] The in memory docs.
+          #
+          # @since 2.1.0
+          def in_memory
+            docs = (_loaded.values + _added.values)
+            docs.each do |doc|
+              yield(doc) if block_given?
             end
+          end
 
-            # Get the last document in the enumerable. Will check the new
-            # documents first. Does not load the entire enumerable.
-            #
-            # @example Get the last document.
-            #   enumerable.last
-            #
-            # @note Automatically adding a sort on _id when no other sort is
-            #   defined on the criteria has the potential to cause bad performance issues.
-            #   If you experience unexpected poor performance when using #first or #last,
-            #   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.
-            #
-            # @option opts [ :none ] :id_sort Don't apply a sort on _id.
-            #
-            # @return [ Document ] The last document found.
-            #
-            # @since 2.1.0
-            def last(opts = {})
-              _added.values.try(:last) ||
-                  _loaded.try(:values).try(:last) ||
-                  _added[(ul = _unloaded.try(:last, opts)).try(:id)] ||
-                  ul
-            end
+          # Get the last document in the enumerable. Will check the new
+          # documents first. Does not load the entire enumerable.
+          #
+          # @example Get the last document.
+          #   enumerable.last
+          #
+          # @note Automatically adding a sort on _id when no other sort is
+          #   defined on the criteria has the potential to cause bad performance issues.
+          #   If you experience unexpected poor performance when using #first or #last,
+          #   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.
+          #
+          # @option opts [ :none ] :id_sort Don't apply a sort on _id.
+          #
+          # @return [ Document ] The last document found.
+          #
+          # @since 2.1.0
+          def last(opts = {})
+            _added.values.try(:last) ||
+                _loaded.try(:values).try(:last) ||
+                _added[(ul = _unloaded.try(:last, opts)).try(:_id)] ||
+                ul
+          end
 
-            # Loads all the documents in the enumerable from the database.
-            #
-            # @example Load all the documents.
-            #   enumerable.load_all!
-            #
-            # @return [ true ] That the enumerable is _loaded.
-            #
-            # @since 2.1.0
-            alias :load_all! :entries
-
-            # Has the enumerable been _loaded? This will be true if the criteria has
-            # been executed or we manually load the entire thing.
-            #
-            # @example Is the enumerable _loaded?
-            #   enumerable._loaded?
-            #
-            # @return [ true, false ] If the enumerable has been _loaded.
-            #
-            # @since 2.1.0
-            def _loaded?
-              !!@executed
-            end
+          # Loads all the documents in the enumerable from the database.
+          #
+          # @example Load all the documents.
+          #   enumerable.load_all!
+          #
+          # @return [ true ] That the enumerable is _loaded.
+          #
+          # @since 2.1.0
+          alias :load_all! :entries
+
+          # Has the enumerable been _loaded? This will be true if the criteria has
+          # been executed or we manually load the entire thing.
+          #
+          # @example Is the enumerable _loaded?
+          #   enumerable._loaded?
+          #
+          # @return [ true, false ] If the enumerable has been _loaded.
+          #
+          # @since 2.1.0
+          def _loaded?
+            !!@executed
+          end
 
-            # Provides the data needed to Marshal.dump an enumerable proxy.
-            #
-            # @example Dump the proxy.
-            #   Marshal.dump(proxy)
-            #
-            # @return [ Array<Object> ] The dumped data.
-            #
-            # @since 3.0.15
-            def marshal_dump
-              [_added, _loaded, _unloaded, @executed]
-            end
+          # Provides the data needed to Marshal.dump an enumerable proxy.
+          #
+          # @example Dump the proxy.
+          #   Marshal.dump(proxy)
+          #
+          # @return [ Array<Object> ] The dumped data.
+          #
+          # @since 3.0.15
+          def marshal_dump
+            [_added, _loaded, _unloaded, @executed]
+          end
 
-            # Loads the data needed to Marshal.load an enumerable proxy.
-            #
-            # @example Load the proxy.
-            #   Marshal.load(proxy)
-            #
-            # @return [ Array<Object> ] The dumped data.
-            #
-            # @since 3.0.15
-            def marshal_load(data)
-              @_added, @_loaded, @_unloaded, @executed = data
-            end
+          # Loads the data needed to Marshal.load an enumerable proxy.
+          #
+          # @example Load the proxy.
+          #   Marshal.load(proxy)
+          #
+          # @return [ Array<Object> ] The dumped data.
+          #
+          # @since 3.0.15
+          def marshal_load(data)
+            @_added, @_loaded, @_unloaded, @executed = data
+          end
 
-            # Reset the enumerable back to its persisted state.
-            #
-            # @example Reset the enumerable.
-            #   enumerable.reset
-            #
-            # @return [ false ] Always false.
-            #
-            # @since 2.1.0
-            def reset
-              _loaded.clear
-              _added.clear
-              @executed = false
-            end
+          # Reset the enumerable back to its persisted state.
+          #
+          # @example Reset the enumerable.
+          #   enumerable.reset
+          #
+          # @return [ false ] Always false.
+          #
+          # @since 2.1.0
+          def reset
+            _loaded.clear
+            _added.clear
+            @executed = false
+          end
 
-            # Resets the underlying unloaded criteria object with a new one. Used
-            # my HABTM associations to keep the underlying array in sync.
-            #
-            # @example Reset the unloaded documents.
-            #   enumerable.reset_unloaded(criteria)
-            #
-            # @param [ Criteria ] criteria The criteria to replace with.
-            #
-            # @since 3.0.14
-            def reset_unloaded(criteria)
-              @_unloaded = criteria if _unloaded.is_a?(Criteria)
-            end
+          # Resets the underlying unloaded criteria object with a new one. Used
+          # my HABTM associations to keep the underlying array in sync.
+          #
+          # @example Reset the unloaded documents.
+          #   enumerable.reset_unloaded(criteria)
+          #
+          # @param [ Criteria ] criteria The criteria to replace with.
+          #
+          # @since 3.0.14
+          def reset_unloaded(criteria)
+            @_unloaded = criteria if _unloaded.is_a?(Criteria)
+          end
 
-            # Does this enumerable respond to the provided method?
-            #
-            # @example Does the enumerable respond to the method?
-            #   enumerable.respond_to?(:sum)
-            #
-            # @param [ String, Symbol ] name The name of the method.
-            # @param [ true, false ] include_private Whether to include private
-            #   methods.
-            #
-            # @return [ true, false ] Whether the enumerable responds.
-            #
-            # @since 2.1.0
-            def respond_to?(name, include_private = false)
-              [].respond_to?(name, include_private) || super
-            end
+          # Does this enumerable respond to the provided method?
+          #
+          # @example Does the enumerable respond to the method?
+          #   enumerable.respond_to?(:sum)
+          #
+          # @param [ String, Symbol ] name The name of the method.
+          # @param [ true, false ] include_private Whether to include private
+          #   methods.
+          #
+          # @return [ true, false ] Whether the enumerable responds.
+          #
+          # @since 2.1.0
+          def respond_to?(name, include_private = false)
+            [].respond_to?(name, include_private) || super
+          end
 
-            # Gets the total size of this enumerable. This is a combination of all
-            # the persisted and unpersisted documents.
-            #
-            # @example Get the size.
-            #   enumerable.size
-            #
-            # @return [ Integer ] The size of the enumerable.
-            #
-            # @since 2.1.0
-            def size
-              count = (_unloaded ? _unloaded.count : _loaded.count)
-              if count.zero?
-                count + _added.count
-              else
-                count + _added.values.count { |d| d.new_record? }
-              end
+          # Gets the total size of this enumerable. This is a combination of all
+          # the persisted and unpersisted documents.
+          #
+          # @example Get the size.
+          #   enumerable.size
+          #
+          # @return [ Integer ] The size of the enumerable.
+          #
+          # @since 2.1.0
+          def size
+            count = (_unloaded ? _unloaded.count : _loaded.count)
+            if count.zero?
+              count + _added.count
+            else
+              count + _added.values.count { |d| d.new_record? }
             end
+          end
 
-            alias :length :size
-
-            # Send #to_json to the entries.
-            #
-            # @example Get the enumerable as json.
-            #   enumerable.to_json
-            #
-            # @param [ Hash ] options Optional parameters.
-            #
-            # @return [ String ] The entries all _loaded as a string.
-            #
-            # @since 2.2.0
-            def to_json(options = {})
-              entries.to_json(options)
-            end
+          alias :length :size
+
+          # Send #to_json to the entries.
+          #
+          # @example Get the enumerable as json.
+          #   enumerable.to_json
+          #
+          # @param [ Hash ] options Optional parameters.
+          #
+          # @return [ String ] The entries all _loaded as a string.
+          #
+          # @since 2.2.0
+          def to_json(options = {})
+            entries.to_json(options)
+          end
 
-            # Send #as_json to the entries, without encoding.
-            #
-            # @example Get the enumerable as json.
-            #   enumerable.as_json
-            #
-            # @param [ Hash ] options Optional parameters.
-            #
-            # @return [ Hash ] The entries all _loaded as a hash.
-            #
-            # @since 2.2.0
-            def as_json(options = {})
-              entries.as_json(options)
-            end
+          # Send #as_json to the entries, without encoding.
+          #
+          # @example Get the enumerable as json.
+          #   enumerable.as_json
+          #
+          # @param [ Hash ] options Optional parameters.
+          #
+          # @return [ Hash ] The entries all _loaded as a hash.
+          #
+          # @since 2.2.0
+          def as_json(options = {})
+            entries.as_json(options)
+          end
 
-            # Return all the unique documents in the enumerable.
-            #
-            # @note This operation loads all documents from the database.
-            #
-            # @example Get all the unique documents.
-            #   enumerable.uniq
-            #
-            # @return [ Array<Document> ] The unique documents.
-            #
-            # @since 2.1.0
-            def uniq
-              entries.uniq
-            end
+          # Return all the unique documents in the enumerable.
+          #
+          # @note This operation loads all documents from the database.
+          #
+          # @example Get all the unique documents.
+          #   enumerable.uniq
+          #
+          # @return [ Array<Document> ] The unique documents.
+          #
+          # @since 2.1.0
+          def uniq
+            entries.uniq
+          end
 
-            private
+          private
 
-            def set_base(document)
-              if @_association.is_a?(Referenced::HasMany)
-                document.set_relation(@_association.inverse, @_base) if @_association
-              end
+          def set_base(document)
+            if @_association.is_a?(Referenced::HasMany)
+              document.set_relation(@_association.inverse, @_base) if @_association
             end
+          end
 
-            def method_missing(name, *args, &block)
-              entries.send(name, *args, &block)
-            end
+          def method_missing(name, *args, &block)
+            entries.send(name, *args, &block)
+          end
 
-            def unloaded_documents
-              if _unloaded.selector._mongoid_unsatisfiable_criteria?
-                []
-              else
-                _unloaded
-              end
+          def unloaded_documents
+            if _unloaded.selector._mongoid_unsatisfiable_criteria?
+              []
+            else
+              _unloaded
             end
           end
         end