mongoid 8.1.5 → 9.0.0

data/lib/mongoid/association/macros.rb

@@ -2,7 +2,6 @@
 
 module Mongoid
   module Association
-
     # This module contains the core macros for defining associations between
     # documents. They can be either embedded or referenced.
     module Macros
@@ -35,7 +34,7 @@ module Mongoid
         # @api private
         class_attribute :aliased_associations
 
-        # @return [ Set<String> ] The set of associations that are configured 
+        # @return [ Set<String> ] The set of associations that are configured
         #   with :store_as parameter.
         class_attribute :stored_as_associations
 
@@ -53,11 +52,11 @@ module Mongoid
       #
       # @return [ Hash ] The associations.
       def associations
-        self.relations
+        relations
       end
 
+      # Class methods for associations.
       module ClassMethods
-
         # Adds the association back to the parent document. This macro is
         # necessary to set the references from the child back to the parent
         # document. If a child does not define this association calling
@@ -77,7 +76,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embedded_in(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -100,7 +99,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embeds_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -123,7 +122,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def embeds_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -145,11 +144,13 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def belongs_to(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
+        # rubocop:disable Naming/PredicateName
+
         # Adds a referenced association from a parent Document to many
         # Documents in another database or collection.
         #
@@ -167,7 +168,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -189,7 +190,7 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_and_belongs_to_many(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
@@ -211,20 +212,22 @@ module Mongoid
         #
         # @param [ Symbol ] name The name of the association.
         # @param [ Hash ] options The association options.
-        # @param [ Proc ] block Optional block for defining extensions.
+        # @param &block Optional block for defining extensions.
         def has_one(name, options = {}, &block)
           define_association!(__method__, name, options, &block)
         end
 
+        # rubocop:enable Naming/PredicateName
+
         private
 
         def define_association!(macro_name, name, options = {}, &block)
           Association::MACRO_MAPPING[macro_name].new(self, name, options, &block).tap do |assoc|
             assoc.setup!
-            self.relations = self.relations.merge(name => assoc)
+            self.relations = relations.merge(name => assoc)
             if assoc.embedded? && assoc.respond_to?(:store_as) && assoc.store_as != name
-              self.aliased_associations[assoc.store_as] = name
-              self.stored_as_associations << assoc.store_as
+              aliased_associations[assoc.store_as] = name
+              stored_as_associations << assoc.store_as
             end
           end
         end

data/lib/mongoid/association/many.rb

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

data/lib/mongoid/association/marshalable.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
+
+    # Mixin module for Mongoid::Association::Proxy which adds
+    # custom Marshal.dump functionality.
     module Marshalable
 
       # Provides the data needed to Marshal.dump an association proxy.

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

@@ -1,8 +1,12 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Builder class used to perform #accepts_nested_attributes_for
+      # attribute assignment on many-to-n associations.
       class Many
         include Buildable
 
@@ -40,7 +44,7 @@ module Mongoid
         # @example Initialize the builder.
         #   Many.new(association, attributes, options)
         #
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         # @param [ Hash ] attributes The attributes hash to attempt to set.
         # @param [ Hash ] options The options defined.
         def initialize(association, attributes, options = {})
@@ -97,7 +101,8 @@ module Mongoid
         # @param [ Hash ] attrs The single document attributes to process.
         def process_attributes(parent, attrs)
           return if reject?(parent, attrs)
-          if id = attrs.extract_id
+
+          if (id = extract_id(attrs))
             update_nested_relation(parent, id, attrs)
           else
             existing.push(Factory.build(@class_name, attrs)) unless destroyable?(attrs)
@@ -149,7 +154,7 @@ module Mongoid
         # @param [ Document ] doc The document to update.
         # @param [ Hash ] attrs The attributes.
         def update_document(doc, attrs)
-          attrs.delete_id
+          delete_id(attrs)
           if association.embedded?
             doc.assign_attributes(attrs)
           else

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

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Mixin module containing common functionality used to
+      # perform #accepts_nested_attributes_for attribute assignment
+      # on associations.
       module Buildable
 
         attr_accessor :attributes, :existing, :association, :options
@@ -60,6 +65,33 @@ module Mongoid
         def convert_id(klass, id)
           klass.using_object_ids? ? BSON::ObjectId.mongoize(id) : id
         end
+
+        private
+
+        # Get the id attribute from the given hash, whether it's
+        # prefixed with an underscore or is a symbol.
+        #
+        # @example Get the id.
+        #   extract_id({ _id: 1 })
+        #
+        # @param [ Hash ] hash The hash from which to extract.
+        #
+        # @return [ Object ] The value of the id.
+        def extract_id(hash)
+          hash['_id'] || hash[:_id] || hash['id'] || hash[:id]
+        end
+
+        # Deletes the id key from the given hash.
+        #
+        # @example Delete an id value.
+        #   delete_id({ "_id" => 1 })
+        #
+        # @param [ Hash ] hash The hash from which to delete.
+        #
+        # @return [ Object ] The deleted value, or nil.
+        def delete_id(hash)
+          hash.delete('_id') || hash.delete(:_id) || hash.delete('id') || hash.delete(:id)
+        end
       end
     end
   end

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

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Nested
+
+      # Builder class used to perform #accepts_nested_attributes_for
+      # attribute assignment on one-to-n associations.
       class One
         include Buildable
 
         attr_accessor :destroy
 
-
         # Builds the association depending on the attributes and the options
         # passed to the macro.
         #
@@ -26,7 +29,7 @@ module Mongoid
           return if reject?(parent, attributes)
           @existing = parent.send(association.name)
           if update?
-            attributes.delete_id
+            delete_id(attributes)
             existing.assign_attributes(attributes)
           elsif replace?
             parent.send(association.setter, Factory.build(@class_name, attributes))
@@ -43,7 +46,7 @@ module Mongoid
         # @example Instantiate the builder.
         #   One.new(association, attributes)
         #
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         # @param [ Hash ] attributes The attributes hash to attempt to set.
         # @param [ Hash ] options The options defined.
         def initialize(association, attributes, options)

data/lib/mongoid/association/nested.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require 'mongoid/association/nested/nested_buildable'
 require 'mongoid/association/nested/many'

data/lib/mongoid/association/one.rb

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

data/lib/mongoid/association/options.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
 
+    # Options context used for all association types.
     module Options
 
       # Returns the name of the parent to a polymorphic child.
@@ -112,8 +114,13 @@ module Mongoid
         @touch_field ||= options[:touch] if (options[:touch].is_a?(String) || options[:touch].is_a?(Symbol))
       end
 
-      private
-
+      # Whether the association object should be automatically touched
+      # when its inverse object is updated.
+      #
+      # @return [ true | false ] returns true if this association is
+      #   automatically touched, false otherwise. The default is false.
+      #
+      # @api private
       def touchable?
         !!@options[:touch]
       end

data/lib/mongoid/association/proxy.rb

@@ -1,21 +1,32 @@
 # frozen_string_literal: true
 
-require "mongoid/association/marshalable"
+require 'mongoid/association/marshalable'
 
 module Mongoid
   module Association
-
     # This class is the superclass for all association proxy objects, and contains
     # common behavior for all of them.
     class Proxy
       extend Forwardable
 
-      alias :extend_proxy :extend
+      alias extend_proxy extend
+
+      # specific methods to prevent from being undefined
+      KEEPER_METHODS = %i[
+        send
+        object_id
+        equal?
+        respond_to?
+        respond_to_missing?
+        tap
+        public_send
+        extend_proxy
+        extend_proxies
+      ].freeze
 
       # 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\?|respond_to_missing\?|tap|public_send|extend_proxy|extend_proxies)\z/
+        undef_method(method) unless method.to_s.start_with?('__') || KEEPER_METHODS.include?(method)
       end
 
       include Threaded::Lifecycle
@@ -41,16 +52,12 @@ module Mongoid
       def_delegators :binding, :bind_one, :unbind_one
       def_delegator :_base, :collection_name
 
-      # Convenience for setting the target and the association metadata properties since
-      # all proxies will need to do this.
-      #
-      # @example Initialize the proxy.
-      #   proxy.init(person, name, association)
+      # Sets the target and the association metadata properties.
       #
       # @param [ Document ] base The base document on the proxy.
       # @param [ Document | Array<Document> ] target The target of the proxy.
-      # @param [ Association ] association The association metadata.
-      def init(base, target, association)
+      # @param [ Mongoid::Association::Relatable ] association The association metadata.
+      def initialize(base, target, association)
         @_base, @_target, @_association = base, target, association
         yield(self) if block_given?
         extend_proxies(association.extension) if association.extension
@@ -58,7 +65,7 @@ module Mongoid
 
       # Allow extension to be an array and extend each module
       def extend_proxies(*extension)
-        extension.flatten.each {|ext| extend_proxy(ext) }
+        extension.flatten.each { |ext| extend_proxy(ext) }
       end
 
       # Get the class from the association, or return nil if no association present.
@@ -68,7 +75,7 @@ module Mongoid
       #
       # @return [ Class ] The association class.
       def klass
-        _association ? _association.klass : nil
+        _association&.klass
       end
 
       # Resets the criteria inside the association proxy. Used by many to many
@@ -119,10 +126,16 @@ module Mongoid
       #
       # @param [ String | Symbol ] name The name of the method.
       # @param [ Object... ] *args The arguments passed to the method.
+      # @param &block Optional block to pass.
       ruby2_keywords def method_missing(name, *args, &block)
         _target.send(name, *args, &block)
       end
 
+      # Whether the proxy can forward the method to the target.
+      #
+      # @param [ String | Symbol ] name The name of the method.
+      # @param [ Object... ] *args The +respond_to?+ arguments.
+      #
       # @api private
       ruby2_keywords def respond_to_missing?(name, *args)
         _target.respond_to?(name, *args)
@@ -174,21 +187,20 @@ module Mongoid
       #
       # @return [ Object ] The result of the given block
       def execute_callbacks_around(name, doc)
-        execute_callback :"before_#{name.to_s}", doc
+        execute_callback :"before_#{name}", doc
         yield.tap do
-          execute_callback :"after_#{name.to_s}", doc
+          execute_callback :"after_#{name}", doc
         end
       end
 
       class << self
-
         # Apply ordering to the criteria if it was defined on the association.
         #
         # @example Apply the ordering.
         #   Proxy.apply_ordering(criteria, association)
         #
         # @param [ Criteria ] criteria The criteria to modify.
-        # @param [ Association ] association The association metadata.
+        # @param [ Mongoid::Association::Relatable ] association The association metadata.
         #
         # @return [ Criteria ] The ordered criteria.
         def apply_ordering(criteria, association)

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

@@ -1,9 +1,13 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Referenced
 
+      # Mixin module included into Mongoid::Document which adds
+      # the ability to automatically save opposite-side documents
+      # in referenced associations when saving the subject document.
       module AutoSave
         extend ActiveSupport::Concern
 
@@ -43,7 +47,7 @@ module Mongoid
         # @example Define the autosave method:
         #   Association::Referenced::Autosave.define_autosave!(association)
         #
-        # @param [ Association ] association The association for which autosaving is enabled.
+        # @param [ Mongoid::Association::Relatable ] association The association for which autosaving is enabled.
         #
         # @return [ Class ] The association's owner class.
         def self.define_autosave!(association)
@@ -56,7 +60,7 @@ module Mongoid
                 __autosaving__ do
                   if assoc_value = ivar(association.name)
                     Array(assoc_value).each do |doc|
-                      pc = doc.persistence_context? ? doc.persistence_context : persistence_context
+                      pc = doc.persistence_context? ? doc.persistence_context : persistence_context.for_child(doc)
                       doc.with(pc) do |d|
                         d.save
                       end

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

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

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

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

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -6,7 +7,7 @@ module Mongoid
       class BelongsTo
 
         # Eager class for belongs_to associations.
-        class Eager < Association::Referenced::Eager::Base
+        class Eager < Association::Eager
 
           private
 

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

@@ -4,11 +4,13 @@ module Mongoid
   module Association
     module Referenced
       class BelongsTo
-
-        # This class handles all behavior for associations that are either
-        # one-to-many or one-to-one, where the foreign key is stored on this side
-        # of the association and the reference is to document(s) in another
-        # collection.
+        # Transparent proxy for belong_to 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
           include Evolvable
 
@@ -20,9 +22,9 @@ module Mongoid
           # @param [ Document ] base The document this association hangs off of.
           # @param [ Document | Array<Document> ] target The target (parent) of the
           #   association.
-          # @param [ Association ] association The association object.
+          # @param [ Mongoid::Association::Relatable ] association The association object.
           def initialize(base, target, association)
-            init(base, target, association) do
+            super do
               characterize_one(_target)
               bind_one
             end
@@ -50,11 +52,11 @@ module Mongoid
           # @return [ self | nil ] The association or nil.
           def substitute(replacement)
             unbind_one
-            if replacement
-              self._target = normalize(replacement)
-              bind_one
-              self
-            end
+            return unless replacement
+
+            self._target = normalize(replacement)
+            bind_one
+            self
           end
 
           private
@@ -81,6 +83,7 @@ module Mongoid
           # @return [ Document ] The document.
           def normalize(replacement)
             return replacement if replacement.is_a?(Document)
+
             _association.build(klass, replacement)
           end
 
@@ -95,13 +98,15 @@ module Mongoid
           end
 
           class << self
-
             # Get the Eager object for this type of association.
             #
             # @example Get the eager loader object
             #
-            # @param [ Association ] association The association object.
+            # @param [ Mongoid::Association::Relatable ] association The association object.
             # @param [ Array<Document> ] docs The array of documents.
+            #
+            # @return [ Mongoid::Association::Referenced::BelongsTo::Eager ]
+            #   The eager loader.
             def eager_loader(association, docs)
               Eager.new(association, docs)
             end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 require 'mongoid/association/referenced/belongs_to/binding'
 require 'mongoid/association/referenced/belongs_to/buildable'
@@ -51,7 +52,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 ||= [ HasMany, HasOne ].freeze
         end

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

@@ -1,8 +1,13 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
     module Referenced
+
+      # Mixin module included into Mongoid::Document which adds
+      # the ability to cache the count of opposite-side documents
+      # in referenced n-to-many associations.
       module CounterCache
         extend ActiveSupport::Concern
 
@@ -88,7 +93,7 @@ module Mongoid
         # @example Add the touchable.
         #   Mongoid::Association::Referenced::CounterCache.define_callbacks!(association)
         #
-        # @param [ Association ] association The association.
+        # @param [ Mongoid::Association::Relatable ] association The association.
         #
         # @return [ Class ] The association's owning class.
         def self.define_callbacks!(association)
@@ -103,7 +108,7 @@ module Mongoid
                 original, current = send("#{foreign_key}_previous_change")
 
                 unless original.nil?
-                  association.klass.with(persistence_context) do |_class|
+                  association.klass.with(persistence_context.for_child(association.klass)) do |_class|
                     _class.decrement_counter(cache_column, original)
                   end
                 end

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -18,11 +19,11 @@ module Mongoid
           # @param [ Document ] doc The single document to bind.
           def bind_one(doc)
             binding do
-              inverse_keys = doc.you_must(_association.inverse_foreign_key)
+              inverse_keys = try_method(doc, _association.inverse_foreign_key) unless doc.frozen?
               if inverse_keys
                 record_id = inverse_record_id(doc)
                 unless inverse_keys.include?(record_id)
-                  doc.you_must(_association.inverse_foreign_key_setter, inverse_keys.push(record_id))
+                  try_method(doc, _association.inverse_foreign_key_setter, inverse_keys.push(record_id))
                 end
                 doc.reset_relation_criteria(_association.inverse)
               end
@@ -38,7 +39,7 @@ module Mongoid
           def unbind_one(doc)
             binding do
               _base.send(_association.foreign_key).delete_one(record_id(doc))
-              inverse_keys = doc.you_must(_association.inverse_foreign_key)
+              inverse_keys = try_method(doc, _association.inverse_foreign_key) unless doc.frozen?
               if inverse_keys
                 inverse_keys.delete_one(inverse_record_id(doc))
                 doc.reset_relation_criteria(_association.inverse)
@@ -49,6 +50,11 @@ module Mongoid
           end
 
           # Find the inverse id referenced by inverse_keys
+          #
+          # @param [ Mongoid::Document ] doc The document for which
+          #   to determine the inverse id.
+          #
+          # @return [ BSON::ObjectId ] The inverse id.
           def inverse_record_id(doc)
             if pk = _association.options[:inverse_primary_key]
               _base.send(pk)
@@ -62,6 +68,12 @@ module Mongoid
             end
           end
 
+          # Find the inverse association given a document.
+          #
+          # @param [ Mongoid::Document ] doc The document for which
+          #   to determine the inverse association.
+          #
+          # @return [ Mongoid::Association::Relatable ] The inverse association.
           def determine_inverse_association(doc)
             doc.relations[_base.class.name.demodulize.underscore.pluralize]
           end

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

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

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

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Association
@@ -6,7 +7,7 @@ module Mongoid
       class HasAndBelongsToMany
 
         # Eager class for has_and_belongs_to_many associations.
-        class Eager < Association::Referenced::Eager::Base
+        class Eager < Association::Eager
 
           private