mongoid 8.1.9 → 9.0.0

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

@@ -1,18 +1,60 @@
 # frozen_string_literal: true
 
+# TODO: consider refactoring this Proxy class, to satisfy the following
+# cops...
+# rubocop:disable Metrics/ClassLength
 module Mongoid
   module Association
     module Referenced
       class HasMany
-
-        # This class defines the behavior for all associations that are a
-        # one-to-many between documents in different collections.
+        # Transparent proxy for has_many associations.
+        # An instance of this class is returned when calling the
+        # association getter method on the subject document. This class
+        # inherits from Mongoid::Association::Proxy and forwards most of its
+        # methods to the target of the association, i.e. the array of
+        # documents on the opposite-side collection which must be loaded.
         class Proxy < Association::Many
           extend Forwardable
 
+          # class-level methods for HasMany::Proxy
+          module ClassMethods
+            def eager_loader(association, docs)
+              Eager.new(association, docs)
+            end
+
+            # Returns true if the association is an embedded one. In this case
+            # always false.
+            #
+            # @example Is this association embedded?
+            #   Referenced::Many.embedded?
+            #
+            # @return [ false ] Always false.
+            def embedded?
+              false
+            end
+          end
+
+          extend ClassMethods
+
           def_delegator :criteria, :count
           def_delegators :_target, :first, :in_memory, :last, :reset, :uniq
 
+          # Instantiate a new references_many association. Will set the foreign key
+          # and the base on the inverse object.
+          #
+          # @example Create the new association.
+          #   Referenced::Many.new(base, target, association)
+          #
+          # @param [ Document ] base The document this association hangs off of.
+          # @param [ Array<Document> ] target The target of the association.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
+          def initialize(base, target, association)
+            enum = HasMany::Enumerable.new(target, base, association)
+            super(base, enum, association) do
+              raise_mixed if klass.embedded? && !klass.cyclic?
+            end
+          end
+
           # Appends a document or array of documents to the association. Will set
           # the parent and update the index in the process.
           #
@@ -31,14 +73,15 @@ module Mongoid
           def <<(*args)
             docs = args.flatten
             return concat(docs) if docs.size > 1
-            if doc = docs.first
+
+            if (doc = docs.first)
               append(doc)
               doc.save if persistable? && !_assigning? && !doc.validated?
             end
             self
           end
 
-          alias :push :<<
+          alias push <<
 
           # Appends an array of documents to the association. Performs a batch
           # insert of the documents instead of persisting one at a time.
@@ -53,9 +96,11 @@ module Mongoid
             docs, inserts = [], []
             documents.each do |doc|
               next unless doc
+
               append(doc)
               save_or_delay(doc, docs, inserts) if persistable?
             end
+
             persist_delayed(docs, inserts)
             self
           end
@@ -71,16 +116,16 @@ module Mongoid
           #
           # @return [ Document ] The new document.
           def build(attributes = {}, type = nil)
-            doc = Factory.execute_build(type || klass, attributes, execute_callbacks: false)
-            append(doc)
-            doc.apply_post_processed_defaults
-            yield(doc) if block_given?
-            doc.run_pending_callbacks
-            doc.run_callbacks(:build) { doc }
-            doc
+            Factory.execute_build(type || klass, attributes, execute_callbacks: false).tap do |doc|
+              append(doc)
+              doc.apply_post_processed_defaults
+              yield doc if block_given?
+              doc.run_pending_callbacks
+              doc.run_callbacks(:build) { doc }
+            end
           end
 
-          alias :new :build
+          alias new build
 
           # Delete the document from the association. This will set the foreign key
           # on the document to nil. If the dependent options on the association are
@@ -94,14 +139,14 @@ module Mongoid
           # @return [ Document ] The matching document.
           def delete(document)
             execute_callbacks_around(:remove, document) do
-              _target.delete(document) do |doc|
+              result = _target.delete(document) do |doc|
                 if doc
                   unbind_one(doc)
-                  cascade!(doc) if !_assigning?
+                  cascade!(doc) unless _assigning?
                 end
-              end.tap do
-                reset_unloaded
               end
+
+              result.tap { reset_unloaded }
             end
           end
 
@@ -152,9 +197,9 @@ module Mongoid
           #   end
           #
           # @return [ Array<Document> ] The loaded docs.
-          def each
-            if block_given?
-              _target.each { |doc| yield(doc) }
+          def each(&block)
+            if block
+              _target.each(&block)
             else
               to_enum
             end
@@ -213,7 +258,8 @@ module Mongoid
           #   later.
           #
           # @param [ [ Object | Array<Object> ]... ] *args The ids.
-          # @param [ Proc ] block Optional block to pass.
+          # @param &block Optional block to pass.
+          # @yield [ Object ] Yields each enumerable element to the block.
           #
           # @return [ Document | Array<Document> | nil ] A document or matching documents.
           def find(*args, &block)
@@ -222,22 +268,6 @@ module Mongoid
             matching
           end
 
-          # Instantiate a new references_many association. Will set the foreign key
-          # and the base on the inverse object.
-          #
-          # @example Create the new association.
-          #   Referenced::Many.new(base, target, association)
-          #
-          # @param [ Document ] base The document this association hangs off of.
-          # @param [ Array<Document> ] target The target of the association.
-          # @param [ Association ] association The association metadata.
-          def initialize(base, target, association)
-            enum = HasMany::Enumerable.new(target, base, association)
-            init(base, enum, association) do
-              raise_mixed if klass.embedded? && !klass.cyclic?
-            end
-          end
-
           # Removes all associations between the base document and the target
           # documents by deleting the foreign keys and the references, orphaning
           # the target documents in the process.
@@ -252,7 +282,7 @@ module Mongoid
             end
           end
 
-          alias :nullify_all :nullify
+          alias nullify_all nullify
 
           # Clear the association. Will delete the documents from the db if they are
           # already persisted.
@@ -262,27 +292,27 @@ module Mongoid
           #
           # @return [ Many ] The association emptied.
           def purge
-            unless _association.destructive?
-              nullify
-            else
-              after_remove_error = nil
-              criteria.delete_all
-              many = _target.clear do |doc|
-                execute_callback :before_remove, doc
-                unbind_one(doc)
-                doc.destroyed = true
-                begin
-                  execute_callback :after_remove, doc
-                rescue => e
-                  after_remove_error = e
-                end
+            return nullify unless _association.destructive?
+
+            after_remove_error = nil
+            criteria.delete_all
+            many = _target.clear do |doc|
+              execute_callback :before_remove, doc
+              unbind_one(doc)
+              doc.destroyed = true
+              begin
+                execute_callback :after_remove, doc
+              rescue StandardError => e
+                after_remove_error = e
               end
-              raise after_remove_error if after_remove_error
-              many
             end
+
+            raise after_remove_error if after_remove_error
+
+            many
           end
 
-          alias :clear :purge
+          alias clear purge
 
           # Substitutes the supplied target documents for the existing documents
           # in the association. If the new target is nil, perform the necessary
@@ -297,7 +327,7 @@ module Mongoid
           def substitute(replacement)
             if replacement
               new_docs, docs = replacement.compact, []
-              new_ids = new_docs.map { |doc| doc._id }
+              new_ids = new_docs.map(&:_id)
               remove_not_in(new_ids)
               new_docs.each do |doc|
                 docs.push(doc) if doc.send(foreign_key) != _base.send(_association.primary_key)
@@ -363,9 +393,9 @@ module Mongoid
           #   association is persisted.
           def already_related?(document)
             document.persisted? &&
-                document._association &&
-                document.respond_to?(document._association.foreign_key) &&
-                document.__send__(document._association.foreign_key) == _base._id
+              document._association &&
+              document.respond_to?(document._association.foreign_key) &&
+              document.__send__(document._association.foreign_key) == _base._id
           end
 
           # Instantiate the binding associated with this association.
@@ -409,15 +439,15 @@ module Mongoid
           #
           # @return [ true | false ] If the association is destructive.
           def cascade!(document)
-            if persistable?
-              case _association.dependent
-              when :delete_all
-                document.delete
-              when :destroy
-                document.destroy
-              else
-                document.save
-              end
+            return unless persistable?
+
+            case _association.dependent
+            when :delete_all
+              document.delete
+            when :destroy
+              document.destroy
+            else
+              document.save
             end
           end
 
@@ -428,9 +458,13 @@ module Mongoid
           #
           # @param [ Symbol | String ] name The name of the method.
           # @param [ Object... ] *args The method args
-          # @param [ Proc ] block Optional block to pass.
+          # @param &block Optional block to pass.
           #
           # @return [ Criteria | Object ] A Criteria or return value from the target.
+          #
+          # TODO: make sure we are consistingly using respond_to_missing
+          #   anywhere we define method_missing.
+          # rubocop:disable Style/MissingRespondToMissing
           ruby2_keywords def method_missing(name, *args, &block)
             if _target.respond_to?(name)
               _target.send(name, *args, &block)
@@ -440,6 +474,7 @@ module Mongoid
               end
             end
           end
+          # rubocop:enable Style/MissingRespondToMissing
 
           # Persist all the delayed batch inserts.
           #
@@ -451,13 +486,13 @@ module Mongoid
           # @param [ Array<Document> ] docs The delayed inserts.
           # @param [ Array<Hash> ] inserts The raw insert document.
           def persist_delayed(docs, inserts)
-            unless docs.empty?
-              collection.insert_many(inserts, session: _session)
-              docs.each do |doc|
-                doc.new_record = false
-                doc.run_after_callbacks(:create, :save) unless _association.autosave?
-                doc.post_persist
-              end
+            return if docs.empty?
+
+            collection.insert_many(inserts, session: _session)
+            docs.each do |doc|
+              doc.new_record = false
+              doc.run_after_callbacks(:create, :save) unless _association.autosave?
+              doc.post_persist
             end
           end
 
@@ -468,7 +503,7 @@ module Mongoid
           #
           # @return [ true | false ] If the association is persistable.
           def persistable?
-            !_binding? && (_creating? || _base.persisted? && !_building?)
+            !_binding? && (_creating? || (_base.persisted? && !_building?))
           end
 
           # Deletes all related documents from the database given the supplied
@@ -504,20 +539,29 @@ module Mongoid
           # @param [ Array<Object> ] ids The ids.
           def remove_not_in(ids)
             removed = criteria.not_in(_id: ids)
+
+            update_or_delete_all(removed)
+
+            in_memory.each do |doc|
+              next if ids.include?(doc._id)
+
+              unbind_one(doc)
+              _target.delete(doc)
+              doc.destroyed = true if _association.destructive?
+            end
+          end
+
+          # If the association is destructive, the matching documents will
+          # be removed. Otherwise, their foreign keys will be set to nil.
+          #
+          # @param [ Criteria ] removed The criteria for the documents to
+          #   remove.
+          def update_or_delete_all(removed)
             if _association.destructive?
               removed.delete_all
             else
               removed.update_all(foreign_key => nil)
             end
-            in_memory.each do |doc|
-              if !ids.include?(doc._id)
-                unbind_one(doc)
-                _target.delete(doc)
-                if _association.destructive?
-                  doc.destroyed = true
-                end
-              end
-            end
           end
 
           # Save a persisted document immediately or delay a new document for
@@ -539,26 +583,9 @@ module Mongoid
               doc.save
             end
           end
-
-          class << self
-
-            def eager_loader(association, docs)
-              Eager.new(association, docs)
-            end
-
-            # Returns true if the association is an embedded one. In this case
-            # always false.
-            #
-            # @example Is this association embedded?
-            #   Referenced::Many.embedded?
-            #
-            # @return [ false ] Always false.
-            def embedded?
-              false
-            end
-          end
         end
       end
     end
   end
 end
+# rubocop:enable Metrics/ClassLength

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require 'mongoid/association/referenced/has_many/binding'
 require 'mongoid/association/referenced/has_many/buildable'
@@ -46,7 +47,7 @@ module Mongoid
 
         # The list of association complements.
         #
-        # @return [ Array<Association> ] The association complements.
+        # @return [ Array<Mongoid::Association::Relatable> ] The association complements.
         def relation_complements
           @relation_complements ||= [ Referenced::BelongsTo ].freeze
         end

data/lib/mongoid/association/referenced/has_one/binding.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association

data/lib/mongoid/association/referenced/has_one/buildable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association

data/lib/mongoid/association/referenced/has_one/eager.rb

@@ -1,12 +1,12 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Referenced
-
       class HasOne
-
-        class Eager < Association::Referenced::Eager::Base
+        # Eager class for has_one associations.
+        class Eager < Association::Eager
 
           private
 

data/lib/mongoid/association/referenced/has_one/proxy.rb

@@ -4,10 +4,32 @@ module Mongoid
   module Association
     module Referenced
       class HasOne
-
-        # This class defines the behavior for all associations that are a
-        # one-to-one between documents in different collections.
+        # Transparent proxy for has_one associations.
+        # An instance of this class is returned when calling the
+        # association getter method on the subject document. This class
+        # inherits from Mongoid::Association::Proxy and forwards most of
+        # its methods to the target of the association, i.e. the
+        # document on the opposite-side collection which must be loaded.
         class Proxy < Association::One
+          # class-level methods for the HasOne::Proxy
+          module ClassMethods
+            def eager_loader(association, docs)
+              Eager.new(association, docs)
+            end
+
+            # Returns true if the association is an embedded one. In this case
+            # always false.
+            #
+            # @example Is this association embedded?
+            #   Referenced::One.embedded?
+            #
+            # @return [ false ] Always false.
+            def embedded?
+              false
+            end
+          end
+
+          extend ClassMethods
 
           # Instantiate a new references_one association. Will set the foreign key
           # and the base on the inverse object.
@@ -17,9 +39,9 @@ module Mongoid
           #
           # @param [ Document ] base The document this association hangs off of.
           # @param [ Document ] target The target (child) of the association.
-          # @param [ Association ] association The association metadata.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           def initialize(base, target, association)
-            init(base, target, association) do
+            super do
               raise_mixed if klass.embedded? && !klass.cyclic?
               characterize_one(_target)
               bind_one
@@ -49,16 +71,7 @@ module Mongoid
           #
           # @return [ One ] The association.
           def substitute(replacement)
-            if self != replacement
-              unbind_one
-              if persistable?
-                if _association.destructive?
-                  send(_association.dependent)
-                else
-                  save if persisted?
-                end
-              end
-            end
+            prepare_for_replacement if self != replacement
             HasOne::Proxy.new(_base, replacement, _association) if replacement
           end
 
@@ -84,21 +97,17 @@ module Mongoid
             _base.persisted? && !_binding? && !_building?
           end
 
-          class << self
+          # Takes the necessary steps to prepare for the current document
+          # to be replaced by a non-nil substitute.
+          def prepare_for_replacement
+            unbind_one
 
-            def eager_loader(association, docs)
-              Eager.new(association, docs)
-            end
+            return unless persistable?
 
-            # Returns true if the association is an embedded one. In this case
-            # always false.
-            #
-            # @example Is this association embedded?
-            #   Referenced::One.embedded?
-            #
-            # @return [ false ] Always false.
-            def embedded?
-              false
+            if _association.destructive?
+              send(_association.dependent)
+            elsif persisted?
+              save
             end
           end
         end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require 'mongoid/association/referenced/has_one/binding'
 require 'mongoid/association/referenced/has_one/buildable'
@@ -41,7 +42,7 @@ module Mongoid
 
         # The list of association complements.
         #
-        # @return [ Array<Association> ] The association complements.
+        # @return [ Array<Mongoid::Association::Relatable> ] The association complements.
         def relation_complements
           @relation_complements ||= [ Referenced::BelongsTo ].freeze
         end
@@ -116,6 +117,9 @@ module Mongoid
           forced_nil_inverse? || (!!inverse && doc.fields.keys.include?(foreign_key))
         end
 
+        # Does this association type store the foreign key?
+        #
+        # @return [ false ] Always false.
         def stores_foreign_key?; false; end
 
         # Get the path calculator for the supplied document.

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -14,7 +15,7 @@ module Mongoid
         # @example Are the foreign keys syncable?
         #   document._syncable?(association)
         #
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         #
         # @return [ true | false ] If we can sync.
         def _syncable?(association)
@@ -48,7 +49,7 @@ module Mongoid
         # @example Update the inverse keys.
         #   document.remove_inverse_keys(association)
         #
-        # @param [ Association ] association The association.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         #
         # @return [ Object ] The updated values.
         def remove_inverse_keys(association)
@@ -63,7 +64,7 @@ module Mongoid
         # @example Update the inverse keys
         #   document.update_inverse_keys(association)
         #
-        # @param [ Association ] association The document association.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         #
         # @return [ Object ] The updated values.
         def update_inverse_keys(association)
@@ -98,7 +99,7 @@ module Mongoid
           # @example Set up the syncing.
           #   Person._synced(association)
           #
-          # @param [ Association ] association The association metadata.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           def _synced(association)
             unless association.forced_nil_inverse?
               synced_save(association)
@@ -117,7 +118,7 @@ module Mongoid
           # @example Set up the save syncing.
           #   Person.synced_save(association)
           #
-          # @param [ Association ] association The association metadata.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           #
           # @return [ Class ] The class getting set up.
           def synced_save(association)
@@ -136,7 +137,7 @@ module Mongoid
           # @example Set up the destroy syncing.
           #   Person.synced_destroy(association)
           #
-          # @param [ Association ] association The association metadata.
+          # @param [ Mongoid::Association::Relatable ] association The association metadata.
           #
           # @return [ Class ] The class getting set up.
           def synced_destroy(association)

data/lib/mongoid/association/referenced.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require 'mongoid/association/referenced/auto_save'
 require 'mongoid/association/referenced/counter_cache'

data/lib/mongoid/association/reflections.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -15,7 +16,7 @@ module Mongoid
       #
       # @param [ String | Symbol ] name The name of the association to find.
       #
-      # @return [ Association ] The matching association metadata.
+      # @return [ Mongoid::Association::Relatable ] The matching association metadata.
       def reflect_on_association(name)
         self.class.reflect_on_association(name)
       end
@@ -27,7 +28,7 @@ module Mongoid
       #
       # @param [ Symbol... ] *macros The association macros.
       #
-      # @return [ Array<Association> ] The matching association metadata.
+      # @return [ Array<Mongoid::Association::Relatable> ] The matching association metadata.
       def reflect_on_all_association(*macros)
         self.class.reflect_on_all_associations(*macros)
       end
@@ -41,7 +42,7 @@ module Mongoid
         #
         # @param [ String | Symbol ] name The name of the association to find.
         #
-        # @return [ Association ] The matching association metadata.
+        # @return [ Mongoid::Association::Relatable ] The matching association metadata.
         def reflect_on_association(name)
           relations[name.to_s]
         end
@@ -53,7 +54,7 @@ module Mongoid
         #
         # @param [ Symbol... ] *macros The association macros.
         #
-        # @return [ Array<Association> ] The matching association metadata.
+        # @return [ Array<Mongoid::Association::Relatable> ] The matching association metadata.
         def reflect_on_all_associations(*macros)
           all_associations = relations.values
           unless macros.empty?