mongoid 7.0.13 → 7.1.0.rc0

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

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 require 'mongoid/association/referenced/has_many/binding'
 require 'mongoid/association/referenced/has_many/buildable'
 require 'mongoid/association/referenced/has_many/proxy'
@@ -119,7 +122,7 @@ module Mongoid
         # @since 7.0
         def stores_foreign_key?; false; end
 
-        # Get the relation proxy class for this association type.
+        # Get the association proxy class for this association type.
         #
         # @return [ Association::HasMany::Proxy ] The proxy class.
         #
@@ -128,9 +131,9 @@ module Mongoid
           Proxy
         end
 
-        # The criteria used for querying this relation.
+        # The criteria used for querying this association.
         #
-        # @return [ Mongoid::Criteria ] The criteria used for querying this relation.
+        # @return [ Mongoid::Criteria ] The criteria used for querying this association.
         #
         # @since 7.0
         def criteria(base)
@@ -139,7 +142,7 @@ module Mongoid
 
         # 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.
         #

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

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -8,7 +10,7 @@ module Mongoid
         class Binding
           include Bindable
 
-          # Binds a single document with the inverse relation. Used
+          # Binds a single document with the inverse association. Used
           # specifically when appending to the proxy.
           #
           # @example Bind one document.

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

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
@@ -16,11 +18,12 @@ module Mongoid
           #   relation.build(meta, attrs)
           #
           # @param [ Object ] base The base object.
-          # @param [ Object ] object The object to use to build the relation.
+          # @param [ Object ] object The object to use to build the association.
           # @param [ String ] type The type of document to query for.
+          # @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)
             return (object || []) unless query?(object)
             return [] if object.is_a?(Array)
             query_criteria(object, base)

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

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

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

@@ -1,11 +1,13 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
       class HasMany
         module Targets
 
-          # This class is the wrapper for all relational associations that have a
+          # This class is the wrapper for all referenced associations that have a
           # target that can be a criteria or array of _loaded documents. This
           # handles both cases or a combination of the two.
           class Enumerable
@@ -213,6 +215,27 @@ module Mongoid
               end
             end
 
+            # Get an arbitrary document in the enumerable. Will check the persisted
+            # documents first. Does not load the entire enumerable.
+            #
+            # @example Get an arbitrary document.
+            #   enumerable.one
+            #
+            # @note Unlike #first, this does not automatically sort the result set.
+            #
+            # @param [ Hash ] opts The options for the query returning the first document.
+            #
+            # @option opts [ :none ] :id_sort Don't apply a sort on _id.
+            #
+            # @return [ Document ] The first document found.
+            #
+            # @since 7.1.0
+            def one(opts = {})
+              opts = opts.dup
+              opts[:id_sort] ||= :none
+              first(opts)
+            end
+
             # Get the first document in the enumerable. Will check the persisted
             # documents first. Does not load the entire enumerable.
             #
@@ -397,7 +420,7 @@ module Mongoid
             end
 
             # Resets the underlying unloaded criteria object with a new one. Used
-            # my HABTM relations to keep the underlying array in sync.
+            # my HABTM associations to keep the underlying array in sync.
             #
             # @example Reset the unloaded documents.
             #   enumerable.reset_unloaded(criteria)
@@ -500,7 +523,11 @@ module Mongoid
             end
 
             def unloaded_documents
-              _unloaded.selector.values.any?(&:blank_criteria?) ? [] : _unloaded
+              if _unloaded.selector._mongoid_unsatisfiable_criteria?
+                []
+              else
+                _unloaded
+              end
             end
           end
         end

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

@@ -1,17 +1,19 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
       class HasMany
 
-        # This class defines the behaviour for all relations that are a
+        # This class defines the behavior for all associations that are a
         # one-to-many between documents in different collections.
         class Proxy < Association::Many
 
           delegate :count, to: :criteria
           delegate :first, :in_memory, :last, :reset, :uniq, to: :_target
 
-          # Appends a document or array of documents to the relation. Will set
+          # Appends a document or array of documents to the association. Will set
           # the parent and update the index in the process.
           #
           # @example Append a document.
@@ -40,7 +42,7 @@ module Mongoid
 
           alias :push :<<
 
-          # Appends an array of documents to the relation. Performs a batch
+          # Appends an array of documents to the association. Performs a batch
           # insert of the documents instead of persisting one at a time.
           #
           # @example Concat with other documents.
@@ -63,9 +65,9 @@ module Mongoid
           end
 
           # Build a new document from the attributes and append it to this
-          # relation without saving.
+          # association without saving.
           #
-          # @example Build a new document on the relation.
+          # @example Build a new document on the association.
           #   person.posts.build(:title => "A new post")
           #
           # @param [ Hash ] attributes The attributes of the new document.
@@ -85,8 +87,8 @@ module Mongoid
 
           alias :new :build
 
-          # Delete the document from the relation. This will set the foreign key
-          # on the document to nil. If the dependent options on the relation are
+          # 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
           # :delete or :destroy the appropriate removal will occur.
           #
           # @example Delete the document.
@@ -111,10 +113,10 @@ module Mongoid
           # Deletes all related documents from the database given the supplied
           # conditions.
           #
-          # @example Delete all documents in the relation.
+          # @example Delete all documents in the association.
           #   person.posts.delete_all
           #
-          # @example Conditonally delete all documents in the relation.
+          # @example Conditonally delete all documents in the association.
           #   person.posts.delete_all({ :title => "Testing" })
           #
           # @param [ Hash ] conditions Optional conditions to delete with.
@@ -129,10 +131,10 @@ module Mongoid
           # Destroys all related documents from the database given the supplied
           # conditions.
           #
-          # @example Destroy all documents in the relation.
+          # @example Destroy all documents in the association.
           #   person.posts.destroy_all
           #
-          # @example Conditonally destroy all documents in the relation.
+          # @example Conditonally destroy all documents in the association.
           #   person.posts.destroy_all({ :title => "Testing" })
           #
           # @param [ Hash ] conditions Optional conditions to destroy with.
@@ -144,10 +146,10 @@ module Mongoid
             remove_all(conditions, :destroy_all)
           end
 
-          # Iterate over each document in the relation and yield to the provided
+          # Iterate over each document in the association and yield to the provided
           # block.
           #
-          # @note This will load the entire relation into memory.
+          # @note This will load the entire association into memory.
           #
           # @example Iterate over the documents.
           #   person.posts.each do |post|
@@ -165,7 +167,7 @@ module Mongoid
             end
           end
 
-          # Determine if any documents in this relation exist in the database.
+          # Determine if any documents in this association exist in the database.
           #
           # @example Are there persisted documents?
           #   person.posts.exists?
@@ -198,14 +200,14 @@ module Mongoid
             matching
           end
 
-          # Instantiate a new references_many relation. Will set the foreign key
+          # Instantiate a new references_many association. Will set the foreign key
           # and the base on the inverse object.
           #
-          # @example Create the new relation.
+          # @example Create the new association.
           #   Referenced::Many.new(base, target, association)
           #
-          # @param [ Document ] base The document this relation hangs off of.
-          # @param [ Array<Document> ] target The target of the relation.
+          # @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
@@ -220,7 +222,7 @@ module Mongoid
           # documents by deleting the foreign keys and the references, orphaning
           # the target documents in the process.
           #
-          # @example Nullify the relation.
+          # @example Nullify the association.
           #   person.posts.nullify
           #
           # @since 2.0.0.rc.1
@@ -234,13 +236,13 @@ module Mongoid
 
           alias :nullify_all :nullify
 
-          # Clear the relation. Will delete the documents from the db if they are
+          # Clear the association. Will delete the documents from the db if they are
           # already persisted.
           #
-          # @example Clear the relation.
+          # @example Clear the association.
           #   person.posts.clear
           #
-          # @return [ Many ] The relation emptied.
+          # @return [ Many ] The association emptied.
           #
           # @since 2.0.0.beta.1
           def purge
@@ -267,15 +269,15 @@ module Mongoid
           alias :clear :purge
 
           # Substitutes the supplied target documents for the existing documents
-          # 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.posts.substitute([ new_post ])
           #
           # @param [ Array<Document> ] replacement The replacement target.
           #
-          # @return [ Many ] The relation.
+          # @return [ Many ] The association.
           #
           # @since 2.0.0.rc.1
           def substitute(replacement)
@@ -311,7 +313,7 @@ module Mongoid
           # Appends the document to the target array, updating the index on the
           # document at the same time.
           #
-          # @example Append the document to the relation.
+          # @example Append the document to the association.
           #   relation.append(document)
           #
           # @param [ Document ] document The document to append to the target.
@@ -326,7 +328,7 @@ module Mongoid
           end
 
           # Execute before/after add callbacks around the block unless the objects
-          # already have a persisted relation.
+          # already have a persisted association.
           #
           # @example Execute before/after add callbacks around the block.
           #   relation.with_add_callbacks(document, false)
@@ -342,7 +344,7 @@ module Mongoid
             execute_callback :after_add, document unless already_related
           end
 
-          # Whether the document and the base already have a persisted relation.
+          # Whether the document and the base already have a persisted association.
           #
           # @example Is the document already related to the base.
           #   relation.already_related?(document)
@@ -350,7 +352,7 @@ module Mongoid
           # @param [ Document ] document The document to possibly append to the target.
           #
           # @return [ true, false ] Whether the document is already related to the base and the
-          #   relation is persisted.
+          #   association is persisted.
           #
           # @since 5.1.0
           def already_related?(document)
@@ -360,7 +362,7 @@ module Mongoid
                 document.__send__(document._association.foreign_key) == _base.id
           end
 
-          # Instantiate the binding associated with this relation.
+          # Instantiate the binding associated with this association.
           #
           # @example Get the binding.
           #   relation.binding([ address ])
@@ -372,12 +374,12 @@ module Mongoid
             HasMany::Binding.new(_base, _target, _association)
           end
 
-          # Get the collection of the relation in question.
+          # Get the collection of the association in question.
           #
-          # @example Get the collection of the relation.
+          # @example Get the collection of the association.
           #   relation.collection
           #
-          # @return [ Collection ] The collection of the relation.
+          # @return [ Collection ] The collection of the association.
           #
           # @since 2.0.2
           def collection
@@ -387,7 +389,7 @@ module Mongoid
           # Returns the criteria object for the target class with its documents set
           # to target.
           #
-          # @example Get a criteria for the relation.
+          # @example Get a criteria for the association.
           #   relation.criteria
           #
           # @return [ Criteria ] A new criteria.
@@ -465,12 +467,12 @@ module Mongoid
             end
           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.
+          # @return [ true, false ] If the association is persistable.
           #
           # @since 2.1.0
           def persistable?
@@ -480,10 +482,10 @@ module Mongoid
           # Deletes all related documents from the database given the supplied
           # conditions.
           #
-          # @example Delete all documents in the relation.
+          # @example Delete all documents in the association.
           #   person.posts.delete_all
           #
-          # @example Conditonally delete all documents in the relation.
+          # @example Conditonally delete all documents in the association.
           #   person.posts.delete_all({ :title => "Testing" })
           #
           # @param [ Hash ] conditions Optional conditions to delete with.
@@ -558,10 +560,10 @@ 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::Many.embedded?
             #
             # @return [ false ] Always false.

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

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
 require 'mongoid/association/referenced/has_one/binding'
 require 'mongoid/association/referenced/has_one/buildable'
 require 'mongoid/association/referenced/has_one/proxy'
@@ -88,7 +91,7 @@ module Mongoid
         # @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.
         #
@@ -120,7 +123,7 @@ module Mongoid
 
         # 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.
         #

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

@@ -1,16 +1,18 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   module Association
     module Referenced
       class HasOne
 
-        # Binding class for has_one relations.
+        # Binding class for has_one associations.
         #
         # @since 7.0
         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