mongoid 7.0.10 → 7.4.0

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

@@ -1,16 +1,15 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Referenced
       class HasOne
 
-        # Binding class for has_one relations.
-        #
-        # @since 7.0
+        # Binding class for has_one associations.
         class Binding
           include Bindable
 
-          # Binds the base object to the inverse of the relation. This is so we
+          # Binds the base object to the inverse of the association. This is so we
           # are referenced to the actual objects themselves on both sides.
           #
           # This case sets the association metadata on the inverse object as well as the
@@ -19,8 +18,6 @@ module Mongoid
           # @example Bind the document.
           #   person.game.bind(:continue => true)
           #   person.game = Game.new
-          #
-          # @since 2.0.0.rc.1
           def bind_one
             binding do
               bind_from_relational_parent(_target)
@@ -33,8 +30,6 @@ module Mongoid
           # @example Unbind the document.
           #   person.game.unbind(:continue => true)
           #   person.game = nil
-          #
-          # @since 2.0.0.rc.1
           def unbind_one
             binding do
               unbind_from_relational_parent(_target)

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

@@ -1,20 +1,24 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Referenced
       class HasOne
 
         # The Builder behavior for has_one associations.
-        #
-        # @since 7.0
         module Buildable
 
           # This method either takes an _id or an object and queries for the
           # inverse side using the id or sets the object after clearing the
           # associated object.
           #
+          # @param [ Object ] base The base object.
+          # @param [ Object ] object The object to use to build the association.
+          # @param [ String ] type The type of the association.
+          # @param [ nil ] selected_fields Must be nil.
+          #
           # @return [ Document ] A single document.
-          def build(base, object, type = nil)
+          def build(base, object, type = nil, selected_fields = nil)
             if query?(object)
               if !base.new_record?
                 execute_query(object, base)
@@ -28,18 +32,28 @@ module Mongoid
           private
 
           def clear_associated(object)
+            unless inverse
+              raise Errors::InverseNotFound.new(
+                  @owner_class,
+                  name,
+                  object.class,
+                  foreign_key,
+              )
+            end
             if object && (associated = object.send(inverse))
               associated.substitute(nil)
             end
           end
 
           def query_criteria(object, base)
-            crit = klass.where(foreign_key => object)
+            crit = klass.criteria
+            crit = crit.apply_scope(scope)
+            crit = crit.where(foreign_key => object)
             with_polymorphic_criterion(crit, base)
           end
 
           def execute_query(object, base)
-            query_criteria(object, base).limit(-1).first(id_sort: :none)
+            query_criteria(object, base).limit(1).first(id_sort: :none)
           end
 
           def with_polymorphic_criterion(criteria, base)

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

@@ -1,4 +1,5 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Referenced

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

@@ -1,4 +1,5 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Referenced
@@ -7,21 +8,19 @@ module Mongoid
 
           attr_accessor :destroy
 
-          # Builds the relation depending on the attributes and the options
+          # Builds the association depending on the attributes and the options
           # passed to the macro.
           #
           # @example Build a 1-1 nested document.
           #   one.build(person, as: :admin)
           #
           # @note This attempts to perform 3 operations, either one of an update of
-          #   the existing relation, a replacement of the relation with a new
-          #   document, or a removal of the relation.
+          #   the existing association, a replacement of the association with a new
+          #   document, or a removal of the association.
           #
           # @param [ Document ] parent The parent document.
           #
           # @return [ Document ] The built document.
-          #
-          # @since 2.0.0
           def build(parent)
             return if reject?(parent, attributes)
             @existing = parent.send(association.name)
@@ -36,7 +35,7 @@ module Mongoid
           end
 
           # Create the new builder for nested attributes on one-to-one
-          # relations.
+          # associations.
           #
           # @example Instantiate the builder.
           #   One.new(association, attributes)
@@ -44,8 +43,6 @@ module Mongoid
           # @param [ Association ] association The association metadata.
           # @param [ Hash ] attributes The attributes hash to attempt to set.
           # @param [ Hash ] options The options defined.
-          #
-          # @since 2.0.0
           def initialize(association, attributes, options)
             @attributes = attributes.with_indifferent_access
             @association = association
@@ -56,7 +53,7 @@ module Mongoid
           private
 
           # Is the id in the attribtues acceptable for allowing an update to
-          # the existing relation?
+          # the existing association?
           #
           # @api private
           #
@@ -64,34 +61,28 @@ module Mongoid
           #   one.acceptable_id?
           #
           # @return [ true, false ] If the id part of the logic will allow an update.
-          #
-          # @since 2.0.0
           def acceptable_id?
-            id = convert_id(existing.class, attributes[:id])
+            id = convert_id(existing.class, attributes[:_id])
             existing._id == id || id.nil? || (existing._id != id && update_only?)
           end
 
-          # Can the existing relation be deleted?
+          # Can the existing association be deleted?
           #
           # @example Can the existing object be deleted?
           #   one.delete?
           #
-          # @return [ true, false ] If the relation should be deleted.
-          #
-          # @since 2.0.0
+          # @return [ true, false ] If the association should be deleted.
           def delete?
-            destroyable? && !attributes[:id].nil?
+            destroyable? && !attributes[:_id].nil?
           end
 
-          # Can the existing relation potentially be destroyed?
+          # Can the existing association potentially be destroyed?
           #
           # @example Is the object destroyable?
           #   one.destroyable?({ :_destroy => "1" })
           #
-          # @return [ true, false ] If the relation can potentially be
+          # @return [ true, false ] If the association can potentially be
           #   destroyed.
-          #
-          # @since 2.0.0
           def destroyable?
             [ 1, "1", true, "true" ].include?(destroy) && allow_destroy?
           end
@@ -102,8 +93,6 @@ module Mongoid
           #   one.replace?
           #
           # @return [ true, false ] If the document should be replaced.
-          #
-          # @since 2.0.0
           def replace?
             !existing && !destroyable? && !attributes.blank?
           end
@@ -114,8 +103,6 @@ module Mongoid
           #   one.update?
           #
           # @return [ true, false ] If the object should have its attributes updated.
-          #
-          # @since 2.0.0
           def update?
             existing && !destroyable? && acceptable_id?
           end

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

@@ -1,21 +1,22 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Referenced
       class HasOne
 
-        # This class defines the behaviour for all relations that are a
+        # This class defines the behavior for all associations that are a
         # one-to-one between documents in different collections.
         class Proxy < Association::One
 
-          # Instantiate a new references_one relation. Will set the foreign key
+          # Instantiate a new references_one association. Will set the foreign key
           # and the base on the inverse object.
           #
-          # @example Create the new relation.
+          # @example Create the new association.
           #   Referenced::One.new(base, target, association)
           #
-          # @param [ Document ] base The document this relation hangs off of.
-          # @param [ Document ] target The target (child) of the relation.
+          # @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.
           def initialize(base, target, association)
             init(base, target, association) do
@@ -30,31 +31,32 @@ module Mongoid
           # document by deleting the foreign key and the reference, orphaning
           # the target document in the process.
           #
-          # @example Nullify the relation.
+          # @example Nullify the association.
           #   person.game.nullify
-          #
-          # @since 2.0.0.rc.1
           def nullify
             unbind_one
             _target.save
           end
 
           # Substitutes the supplied target document for the existing document
-          # in the relation. If the new target is nil, perform the necessary
+          # in the association. If the new target is nil, perform the necessary
           # deletion.
           #
-          # @example Replace the relation.
+          # @example Replace the association.
           #   person.game.substitute(new_game)
           #
           # @param [ Array<Document> ] replacement The replacement target.
           #
-          # @return [ One ] The relation.
-          #
-          # @since 2.0.0.rc.1
+          # @return [ One ] The association.
           def substitute(replacement)
+            # If the same object currently associated is being assigned,
+            # rebind the association and save the target but do not destroy
+            # the target.
+
             unbind_one
             if persistable?
-              if _association.destructive?
+              # TODO can this entire method be skipped if self == replacement?
+              if _association.destructive? && self != replacement
                 send(_association.dependent)
               else
                 save if persisted?
@@ -65,7 +67,7 @@ module Mongoid
 
           private
 
-          # Instantiate the binding associated with this relation.
+          # Instantiate the binding associated with this association.
           #
           # @example Get the binding.
           #   relation.binding([ address ])
@@ -75,14 +77,12 @@ module Mongoid
             HasOne::Binding.new(_base, _target, _association)
           end
 
-          # Are we able to persist this relation?
+          # Are we able to persist this association?
           #
-          # @example Can we persist the relation?
+          # @example Can we persist the association?
           #   relation.persistable?
           #
-          # @return [ true, false ] If the relation is persistable.
-          #
-          # @since 2.1.0
+          # @return [ true, false ] If the association is persistable.
           def persistable?
             _base.persisted? && !_binding? && !_building?
           end
@@ -93,15 +93,13 @@ module Mongoid
               Eager.new(association, docs)
             end
 
-            # Returns true if the relation is an embedded one. In this case
+            # Returns true if the association is an embedded one. In this case
             # always false.
             #
-            # @example Is this relation embedded?
+            # @example Is this association embedded?
             #   Referenced::One.embedded?
             #
             # @return [ false ] Always false.
-            #
-            # @since 2.0.0.rc.1
             def embedded?
               false
             end

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

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'mongoid/association/referenced/has_one/binding'
 require 'mongoid/association/referenced/has_one/buildable'
 require 'mongoid/association/referenced/has_one/proxy'
@@ -8,8 +10,6 @@ module Mongoid
     module Referenced
 
       # The has_one association.
-      #
-      # @since 7.0
       class HasOne
         include Relatable
         include Buildable
@@ -18,37 +18,30 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :as,
             :autobuild,
             :autosave,
             :dependent,
             :foreign_key,
-            :primary_key
+            :primary_key,
+            :scope,
         ].freeze
 
         # The complete list of valid options for this association, including
         # the shared ones.
         #
         # @return [ Array<Symbol> ] The valid options.
-        #
-        # @since 7.0
         VALID_OPTIONS = (ASSOCIATION_OPTIONS + SHARED_OPTIONS).freeze
 
         # The default foreign key suffix.
         #
         # @return [ String ] '_id'
-        #
-        # @since 7.0
         FOREIGN_KEY_SUFFIX = '_id'.freeze
 
         # The list of association complements.
         #
         # @return [ Array<Association> ] The association complements.
-        #
-        # @since 7.0
         def relation_complements
           @relation_complements ||= [ Referenced::BelongsTo ].freeze
         end
@@ -56,8 +49,6 @@ module Mongoid
         # Setup the instance methods, fields, etc. on the association owning class.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup!
           setup_instance_methods!
           self
@@ -67,8 +58,6 @@ module Mongoid
         #
         # @return [ String ] The foreign key field for saving the
         #   association reference.
-        #
-        # @since 7.0
         def foreign_key
           @foreign_key ||= @options[:foreign_key] ? @options[:foreign_key].to_s :
                              default_foreign_key_field
@@ -77,22 +66,16 @@ module Mongoid
         # Is this association type embedded?
         #
         # @return [ false ] Always false.
-        #
-        # @since 7.0
         def embedded?; false; end
 
         # The default for validation the association object.
         #
         # @return [ true ] Always true.
-        #
-        # @since 7.0
         def validation_default; true; end
 
-        # Get the relation proxy class for this association type.
+        # Get the association proxy class for this association type.
         #
         # @return [ Association::HasOne::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
@@ -103,8 +86,6 @@ module Mongoid
         # @param [ Hash ] options The options for the association.
         #
         # @return [ Association::Nested::Many ] The Nested Builder object.
-        #
-        # @since 7.0
         def nested_builder(attributes, options)
           Nested::One.new(self, attributes, options)
         end
@@ -112,19 +93,15 @@ module Mongoid
         # Is this association polymorphic?
         #
         # @return [ true, false ] Whether this association is polymorphic.
-        #
-        # @since 7.0
         def polymorphic?
           @polymorphic ||= !!as
         end
 
         # The type of this association if it's polymorphic.
         #
-        # @note Only relevant for polymorphic relations.
+        # @note Only relevant for polymorphic associations.
         #
         # @return [ String, nil ] The type field.
-        #
-        # @since 7.0
         def type
           @type ||= "#{as}_type" if polymorphic?
         end
@@ -149,19 +126,22 @@ module Mongoid
         # @param [ Document ] document The document to calculate on.
         #
         # @return [ Root ] The root atomic path calculator.
-        #
-        # @since 2.1.0
         def path(document)
           Mongoid::Atomic::Paths::Root.new(document)
         end
 
+        # Get the scope to be applied when querying the association.
+        #
+        # @return [ Proc | Symbol | nil ] The association scope, if any.
+        def scope
+          @options[:scope]
+        end
+
         private
 
         # Setup the instance methods on the class having this association type.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup_instance_methods!
           define_getter!
           define_setter!

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

@@ -1,14 +1,15 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Referenced
 
-      # This module handles the behaviour for synchronizing foreign keys between
-      # both sides of a many to many relations.
+      # This module handles the behavior for synchronizing foreign keys between
+      # both sides of a many to many associations.
       module Syncable
 
         # Is the document able to be synced on the inverse side? This is only if
-        # the key has changed and the relation bindings have not been run.
+        # the key has changed and the association bindings have not been run.
         #
         # @example Are the foreign keys syncable?
         #   document._syncable?(association)
@@ -16,8 +17,6 @@ module Mongoid
         # @param [ Association ] association The association metadata.
         #
         # @return [ true, false ] If we can sync.
-        #
-        # @since 2.1.0
         def _syncable?(association)
           !_synced?(association.foreign_key) && send(association.foreign_key_check)
         end
@@ -28,8 +27,6 @@ module Mongoid
         #   document._synced
         #
         # @return [ Hash ] The synced foreign keys.
-        #
-        # @since 2.1.0
         def _synced
           @_synced ||= {}
         end
@@ -42,8 +39,6 @@ module Mongoid
         # @param [ String ] foreign_key The foreign key.
         #
         # @return [ true, false ] If we can sync.
-        #
-        # @since 2.1.0
         def _synced?(foreign_key)
           !!_synced[foreign_key]
         end
@@ -56,8 +51,6 @@ module Mongoid
         # @param [ Association ] association The association.
         #
         # @return [ Object ] The updated values.
-        #
-        # @since 2.2.1
         def remove_inverse_keys(association)
           foreign_keys = send(association.foreign_key)
           unless foreign_keys.nil? || foreign_keys.empty?
@@ -65,7 +58,7 @@ module Mongoid
           end
         end
 
-        # Update the inverse keys for the relation.
+        # Update the inverse keys for the association.
         #
         # @example Update the inverse keys
         #   document.update_inverse_keys(association)
@@ -73,8 +66,6 @@ module Mongoid
         # @param [ Association ] association The document association.
         #
         # @return [ Object ] The updated values.
-        #
-        # @since 2.1.0
         def update_inverse_keys(association)
           if changes.has_key?(association.foreign_key)
             old, new = changes[association.foreign_key]
@@ -108,8 +99,6 @@ module Mongoid
           #   Person._synced(association)
           #
           # @param [ Association ] association The association metadata.
-          #
-          # @since 2.1.0
           def _synced(association)
             unless association.forced_nil_inverse?
               synced_save(association)
@@ -128,11 +117,9 @@ module Mongoid
           # @example Set up the save syncing.
           #   Person.synced_save(association)
           #
-          # @param [ Association ] association The relation association.
+          # @param [ Association ] association The association metadata.
           #
           # @return [ Class ] The class getting set up.
-          #
-          # @since 2.1.0
           def synced_save(association)
             set_callback(
                 :save,
@@ -152,8 +139,6 @@ module Mongoid
           # @param [ Association ] association The association metadata.
           #
           # @return [ Class ] The class getting set up.
-          #
-          # @since 2.2.1
           def synced_destroy(association)
             set_callback(
                 :destroy,

data/lib/mongoid/association/referenced.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'mongoid/association/referenced/auto_save'
 require 'mongoid/association/referenced/counter_cache'
 require 'mongoid/association/referenced/syncable'

data/lib/mongoid/association/reflections.rb

@@ -1,4 +1,5 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 module Mongoid
   module Association
 
@@ -9,10 +10,10 @@ module Mongoid
 
       # Returns the association metadata for the supplied name.
       #
-      # @example Find relation association by name.
+      # @example Find association metadata by name.
       #   person.reflect_on_association(:addresses)
       #
-      # @param [ String, Symbol ] name The name of the relation to find.
+      # @param [ String, Symbol ] name The name of the association to find.
       #
       # @return [ Association ] The matching association metadata.
       def reflect_on_association(name)
@@ -24,7 +25,7 @@ module Mongoid
       # @example Find multiple association metadata by macro.
       #   person.reflect_on_all_associations(:embeds_many)
       #
-      # @param [ Array<Symbol> ] macros The relation macros.
+      # @param [ Array<Symbol> ] macros The association macros.
       #
       # @return [ Array<Association> ] The matching association metadata.
       def reflect_on_all_association(*macros)
@@ -38,7 +39,7 @@ module Mongoid
         # @example Find association metadata by name.
         #   Person.reflect_on_association(:addresses)
         #
-        # @param [ String, Symbol ] name The name of the relation to find.
+        # @param [ String, Symbol ] name The name of the association to find.
         #
         # @return [ Association ] The matching association metadata.
         def reflect_on_association(name)
@@ -50,7 +51,7 @@ module Mongoid
         # @example Find multiple association metadata by macro.
         #   Person.reflect_on_all_associations(:embeds_many)
         #
-        # @param [ Array<Symbol> ] macros The relation macros.
+        # @param [ Array<Symbol> ] macros The association macros.
         #
         # @return [ Array<Association> ] The matching association metadata.
         def reflect_on_all_associations(*macros)