mongoid 7.3.2 → 7.4.0

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

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
@@ -29,8 +28,6 @@ module Mongoid
           # @param [ Document, Array<Document> ] args Any number of documents.
           #
           # @return [ Array<Document> ] The loaded docs.
-          #
-          # @since 2.0.0.beta.1
           def <<(*args)
             docs = args.flatten
             return concat(docs) if docs.size > 1
@@ -52,8 +49,6 @@ module Mongoid
           # @param [ Array<Document> ] documents The docs to add.
           #
           # @return [ Array<Document> ] The documents.
-          #
-          # @since 2.4.0
           def concat(documents)
             docs, inserts = [], []
             documents.each do |doc|
@@ -75,8 +70,6 @@ module Mongoid
           # @param [ Class ] type The optional subclass to build.
           #
           # @return [ Document ] The new document.
-          #
-          # @since 2.0.0.beta.1
           def build(attributes = {}, type = nil)
             doc = Factory.build(type || klass, attributes)
             append(doc)
@@ -98,8 +91,6 @@ module Mongoid
           # @param [ Document ] document The document to remove.
           #
           # @return [ Document ] The matching document.
-          #
-          # @since 2.1.0
           def delete(document)
             execute_callback :before_remove, document
             _target.delete(document) do |doc|
@@ -123,8 +114,6 @@ module Mongoid
           # @param [ Hash ] conditions Optional conditions to delete with.
           #
           # @return [ Integer ] The number of documents deleted.
-          #
-          # @since 2.0.0.beta.1
           def delete_all(conditions = nil)
             remove_all(conditions, :delete_all)
           end
@@ -135,14 +124,12 @@ module Mongoid
           # @example Destroy all documents in the association.
           #   person.posts.destroy_all
           #
-          # @example Conditonally destroy all documents in the association.
+          # @example Conditionally destroy all documents in the association.
           #   person.posts.destroy_all({ :title => "Testing" })
           #
           # @param [ Hash ] conditions Optional conditions to destroy with.
           #
-          # @return [ Integer ] The number of documents destroyd.
-          #
-          # @since 2.0.0.beta.1
+          # @return [ Integer ] The number of documents destroyed.
           def destroy_all(conditions = nil)
             remove_all(conditions, :destroy_all)
           end
@@ -158,8 +145,6 @@ module Mongoid
           #   end
           #
           # @return [ Array<Document> ] The loaded docs.
-          #
-          # @since 2.1.0
           def each
             if block_given?
               _target.each { |doc| yield(doc) }
@@ -185,25 +170,35 @@ module Mongoid
             criteria.exists?
           end
 
-          # Find the matchind document on the association, either based on id or
+          # Find the matching document on the association, either based on id or
           # conditions.
           #
+          # This method delegates to +Mongoid::Criteria#find+. If this method is
+          # not given a block, it returns one or many documents for the provided
+          # _id values.
+          #
+          # If this method is given a block, it returns the first document
+          # of those found by the current Criteria object for which the block
+          # returns a truthy value.
+          #
           # @example Find by an id.
           #   person.posts.find(BSON::ObjectId.new)
           #
           # @example Find by multiple ids.
           #   person.posts.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
           #
+          # @example Finds the first matching document using a block.
+          #   person.addresses.find { |addr| addr.state == 'CA' }
+          #
           # @note This will keep matching documents in memory for iteration
           #   later.
           #
           # @param [ BSON::ObjectId, Array<BSON::ObjectId> ] args The ids.
+          # @param [ Proc ] block Optional block to pass.
           #
-          # @return [ Document, Criteria ] The matching document(s).
-          #
-          # @since 2.0.0.beta.1
-          def find(*args)
-            matching = criteria.find(*args)
+          # @return [ Document | Array<Document> | nil ] A document or matching documents.
+          def find(*args, &block)
+            matching = criteria.find(*args, &block)
             Array(matching).each { |doc| _target.push(doc) }
             matching
           end
@@ -217,8 +212,6 @@ module Mongoid
           # @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.
-          #
-          # @since 2.0.0.beta.1
           def initialize(base, target, association)
             enum = HasMany::Enumerable.new(target, base, association)
             init(base, enum, association) do
@@ -232,8 +225,6 @@ module Mongoid
           #
           # @example Nullify the association.
           #   person.posts.nullify
-          #
-          # @since 2.0.0.rc.1
           def nullify
             criteria.update_all(foreign_key => nil)
             _target.clear do |doc|
@@ -251,8 +242,6 @@ module Mongoid
           #   person.posts.clear
           #
           # @return [ Many ] The association emptied.
-          #
-          # @since 2.0.0.beta.1
           def purge
             unless _association.destructive?
               nullify
@@ -286,8 +275,6 @@ module Mongoid
           # @param [ Array<Document> ] replacement The replacement target.
           #
           # @return [ Many ] The association.
-          #
-          # @since 2.0.0.rc.1
           def substitute(replacement)
             if replacement
               new_docs, docs = replacement.compact, []
@@ -310,8 +297,6 @@ module Mongoid
           #   person.posts.unscoped
           #
           # @return [ Criteria ] The unscoped criteria.
-          #
-          # @since 2.4.0
           def unscoped
             klass.unscoped.where(foreign_key => _base.send(_association.primary_key))
           end
@@ -325,8 +310,6 @@ module Mongoid
           #   relation.append(document)
           #
           # @param [ Document ] document The document to append to the target.
-          #
-          # @since 2.0.0.rc.1
           def append(document)
             with_add_callbacks(document, already_related?(document)) do
               _target.push(document)
@@ -344,8 +327,6 @@ module Mongoid
           # @param [ Document ] document The document to append to the target.
           # @param [ true, false ] already_related Whether the document is already related
           #   to the target.
-          #
-          # @since 5.1.0
           def with_add_callbacks(document, already_related)
             execute_callback :before_add, document unless already_related
             yield
@@ -361,8 +342,6 @@ module Mongoid
           #
           # @return [ true, false ] Whether the document is already related to the base and the
           #   association is persisted.
-          #
-          # @since 5.1.0
           def already_related?(document)
             document.persisted? &&
                 document._association &&
@@ -376,8 +355,6 @@ module Mongoid
           #   relation.binding([ address ])
           #
           # @return [ Binding ] The binding.
-          #
-          # @since 2.0.0.rc.1
           def binding
             HasMany::Binding.new(_base, _target, _association)
           end
@@ -388,8 +365,6 @@ module Mongoid
           #   relation.collection
           #
           # @return [ Collection ] The collection of the association.
-          #
-          # @since 2.0.2
           def collection
             klass.collection
           end
@@ -401,8 +376,6 @@ module Mongoid
           #   relation.criteria
           #
           # @return [ Criteria ] A new criteria.
-          #
-          # @since 2.0.0.beta.1
           def criteria
             @criteria ||= _association.criteria(_base)
           end
@@ -416,8 +389,6 @@ module Mongoid
           # @param [ Document ] document The document to cascade on.
           #
           # @return [ true, false ] If the association is destructive.
-          #
-          # @since 2.1.0
           def cascade!(document)
             if persistable?
               case _association.dependent
@@ -441,8 +412,6 @@ module Mongoid
           # @param [ Proc ] block Optional block to pass.
           #
           # @return [ Criteria, Object ] A Criteria or return value from the target.
-          #
-          # @since 2.0.0.beta.1
           ruby2_keywords def method_missing(name, *args, &block)
             if _target.respond_to?(name)
               _target.send(name, *args, &block)
@@ -462,8 +431,6 @@ module Mongoid
           #
           # @param [ Array<Document> ] docs The delayed inserts.
           # @param [ Array<Hash> ] inserts The raw insert document.
-          #
-          # @since 3.0.0
           def persist_delayed(docs, inserts)
             unless docs.empty?
               collection.insert_many(inserts, session: _session)
@@ -481,8 +448,6 @@ module Mongoid
           #   relation.persistable?
           #
           # @return [ true, false ] If the association is persistable.
-          #
-          # @since 2.1.0
           def persistable?
             !_binding? && (_creating? || _base.persisted? && !_building?)
           end
@@ -500,8 +465,6 @@ module Mongoid
           # @param [ Symbol ] method The deletion method to call.
           #
           # @return [ Integer ] The number of documents deleted.
-          #
-          # @since 2.1.0
           def remove_all(conditions = nil, method = :delete_all)
             selector = conditions || {}
             removed = klass.send(method, selector.merge!(criteria.selector))
@@ -520,8 +483,6 @@ module Mongoid
           #   proxy.remove_not_in([ id ])
           #
           # @param [ Array<Object> ] ids The ids.
-          #
-          # @since 2.4.0
           def remove_not_in(ids)
             removed = criteria.not_in(_id: ids)
             if _association.destructive?
@@ -550,8 +511,6 @@ module Mongoid
           #
           # @param [ Document ] doc The document.
           # @param [ Array<Document> ] inserts The inserts.
-          #
-          # @since 3.0.0
           def save_or_delay(doc, docs, inserts)
             if doc.new_record? && doc.valid?(:create)
               doc.run_before_callbacks(:save, :create)
@@ -575,8 +534,6 @@ module Mongoid
             #   Referenced::Many.embedded?
             #
             # @return [ false ] Always false.
-            #
-            # @since 2.0.0.rc.1
             def embedded?
               false
             end

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

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 require 'mongoid/association/referenced/has_many/binding'
 require 'mongoid/association/referenced/has_many/buildable'
@@ -12,8 +11,6 @@ module Mongoid
     module Referenced
 
       # The has_many association.
-      #
-      # @since 7.0
       class HasMany
         include Relatable
         include Buildable
@@ -22,8 +19,6 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :after_add,
             :after_remove,
@@ -34,29 +29,24 @@ module Mongoid
             :dependent,
             :foreign_key,
             :order,
-            :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
@@ -64,8 +54,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
@@ -74,8 +62,6 @@ module Mongoid
         # Setup the instance methods on the class having this association type.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup_instance_methods!
           define_getter!
           define_ids_getter!
@@ -94,8 +80,6 @@ module Mongoid
         #
         # @return [ String ] The foreign key field on the inverse 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
@@ -104,29 +88,21 @@ 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
 
         # Does this association type store the foreign key?
         #
         # @return [ true ] Always true.
-        #
-        # @since 7.0
         def stores_foreign_key?; false; end
 
         # Get the association proxy class for this association type.
         #
         # @return [ Association::HasMany::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
@@ -134,8 +110,6 @@ module Mongoid
         # The criteria used for querying this association.
         #
         # @return [ Mongoid::Criteria ] The criteria used for querying this association.
-        #
-        # @since 7.0
         def criteria(base)
           query_criteria(base.send(primary_key), base)
         end
@@ -145,8 +119,6 @@ module Mongoid
         # @note Only relevant for polymorphic associations.
         #
         # @return [ String, nil ] The type field.
-        #
-        # @since 7.0
         def type
           @type ||= "#{as}_type" if polymorphic?
         end
@@ -158,8 +130,6 @@ module Mongoid
         # @param [ Class ] object_class The object class.
         #
         # @return [ Mongoid::Criteria ] The criteria object.
-        #
-        # @since 7.0
         def add_polymorphic_criterion(criteria, object_class)
           if polymorphic?
             criteria.where(type => object_class.name)
@@ -171,8 +141,6 @@ module Mongoid
         # Is this association polymorphic?
         #
         # @return [ true, false ] Whether this association is polymorphic.
-        #
-        # @since 7.0
         def polymorphic?
           @polymorphic ||= !!as
         end
@@ -193,8 +161,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::Many.new(self, attributes, options)
         end
@@ -207,12 +173,17 @@ 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
 
         def default_foreign_key_field
@@ -241,7 +212,9 @@ module Mongoid
         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)
           crit = with_polymorphic_criterion(crit, base)
           crit.association = self
           crit.parent_document = base

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

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
@@ -7,8 +6,6 @@ module Mongoid
       class HasOne
 
         # Binding class for has_one associations.
-        #
-        # @since 7.0
         class Binding
           include Bindable
 
@@ -21,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)
@@ -35,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,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
@@ -7,8 +6,6 @@ module Mongoid
       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
@@ -49,7 +46,9 @@ module Mongoid
           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
 

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

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

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

@@ -1,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
@@ -22,8 +21,6 @@ module Mongoid
           # @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)
@@ -46,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
@@ -66,8 +61,6 @@ 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])
             existing._id == id || id.nil? || (existing._id != id && update_only?)
@@ -79,8 +72,6 @@ module Mongoid
           #   one.delete?
           #
           # @return [ true, false ] If the association should be deleted.
-          #
-          # @since 2.0.0
           def delete?
             destroyable? && !attributes[:_id].nil?
           end
@@ -92,8 +83,6 @@ module Mongoid
           #
           # @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
@@ -104,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
@@ -116,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,5 +1,4 @@
 # frozen_string_literal: true
-# encoding: utf-8
 
 module Mongoid
   module Association
@@ -34,8 +33,6 @@ module Mongoid
           #
           # @example Nullify the association.
           #   person.game.nullify
-          #
-          # @since 2.0.0.rc.1
           def nullify
             unbind_one
             _target.save
@@ -51,8 +48,6 @@ module Mongoid
           # @param [ Array<Document> ] replacement The replacement target.
           #
           # @return [ One ] The association.
-          #
-          # @since 2.0.0.rc.1
           def substitute(replacement)
             # If the same object currently associated is being assigned,
             # rebind the association and save the target but do not destroy
@@ -88,8 +83,6 @@ module Mongoid
           #   relation.persistable?
           #
           # @return [ true, false ] If the association is persistable.
-          #
-          # @since 2.1.0
           def persistable?
             _base.persisted? && !_binding? && !_building?
           end
@@ -107,8 +100,6 @@ module Mongoid
             #   Referenced::One.embedded?
             #
             # @return [ false ] Always false.
-            #
-            # @since 2.0.0.rc.1
             def embedded?
               false
             end