mongoid 6.4.2 → 7.0.3

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

@@ -0,0 +1,510 @@
+# encoding: utf-8
+module Mongoid
+  module Association
+    module Referenced
+      class HasMany
+        module Targets
+
+          # This class is the wrapper for all relational 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
+            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
+
+            delegate :is_a?, :kind_of?, to: []
+
+            # 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
+
+            # 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
+
+            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
+              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
+            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
+              end
+              _added.each_pair do |id, doc|
+                yield(doc)
+              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
+            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
+
+            # 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
+            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
+
+            # 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
+
+            # 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 and _added.clear
+              @executed = false
+            end
+
+            # Resets the underlying unloaded criteria object with a new one. Used
+            # my HABTM relations 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
+
+            # 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
+
+            # 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
+
+            private
+
+            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 unloaded_documents
+              _unloaded.selector.values.any?(&:blank_criteria?) ? [] : _unloaded
+            end
+          end
+        end
+      end
+    end
+  end
+end