mongoid 7.0.0 → 7.4.0

data/lib/mongoid/association/embedded/embedded_in.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'mongoid/association/embedded/embedded_in/binding'
 require 'mongoid/association/embedded/embedded_in/buildable'
 require 'mongoid/association/embedded/embedded_in/proxy'
@@ -7,8 +9,6 @@ module Mongoid
     module Embedded
 
       # The EmbeddedIn type association.
-      #
-      # @since 7.0
       class EmbeddedIn
         include Relatable
         include Buildable
@@ -17,28 +17,22 @@ module Mongoid
         # common ones.
         #
         # @return [ Array<Symbol> ] The extra valid options.
-        #
-        # @since 7.0
         ASSOCIATION_OPTIONS = [
             :autobuild,
             :cyclic,
             :polymorphic,
-            :touch
+            :touch,
         ].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
 
         # Setup the instance methods, fields, etc. on the association owning class.
         #
         # @return [ self ]
-        #
-        # @since 7.0
         def setup!
           setup_instance_methods!
           @owner_class.embedded = true
@@ -48,43 +42,33 @@ module Mongoid
         # Is this association type embedded?
         #
         # @return [ true ] Always true.
-        #
-        # @since 7.0
         def embedded?; true; end
 
         # The primary key
         #
-        # @return [ nil ] Not relevant for this relation
+        # @return [ nil ] Not relevant for this association
         def primary_key; end
 
         # Does this association type store the foreign key?
         #
         # @return [ false ] Always false.
-        #
-        # @since 7.0
         def stores_foreign_key?; false; end
 
         # The default for validating the association object.
         #
         # @return [ false ] Always false.
-        #
-        # @since 7.0
         def validation_default; false; end
 
         # The key that is used to get the attributes for the associated object.
         #
-        # @return [ String ] The name of the relation.
-        #
-        # @since 7.0
+        # @return [ String ] The name of the association.
         def key
           @key ||= name.to_s
         end
 
-        # Get the relation proxy class for this association type.
+        # Get the association proxy class for this association type.
         #
         # @return [ Association::Embedded::EmbeddedIn::Proxy ] The proxy class.
-        #
-        # @since 7.0
         def relation
           Proxy
         end
@@ -92,8 +76,6 @@ module Mongoid
         # Is this association polymorphic?
         #
         # @return [ true, false ] Whether this association is polymorphic.
-        #
-        # @since 7.0
         def polymorphic?
           !!@options[:polymorphic]
         end
@@ -104,8 +86,6 @@ module Mongoid
         # @param [ Hash ] options The options for the association.
         #
         # @return [ Association::Nested::One ] The Nested Builder object.
-        #
-        # @since 7.0
         def nested_builder(attributes, options)
           Nested::One.new(self, attributes, options)
         end

data/lib/mongoid/association/embedded/embeds_many/binding.rb

@@ -1,23 +1,21 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Embedded
       class EmbedsMany
 
-        # Binding class for all embeds_many relations.
-        #
-        # @since 7.0
+        # Binding class for all embeds_many associations.
         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.
           #   person.addresses.bind_one(address)
           #
           # @param [ Document ] doc The single document to bind.
-          #
-          # @since 2.0.0.rc.1
           def bind_one(doc)
             doc.parentize(_base)
             binding do
@@ -31,8 +29,6 @@ module Mongoid
           #   person.addresses.unbind_one(document)
           #
           # @param [ Document ] doc The single document to unbind.
-          #
-          # @since 2.0.0.rc.1
           def unbind_one(doc)
             binding do
               doc.do_or_do_not(_association.inverse_setter(_target), nil)

data/lib/mongoid/association/embedded/embeds_many/buildable.rb

@@ -1,11 +1,11 @@
+# frozen_string_literal: true
+
 module Mongoid
   module Association
     module Embedded
       class EmbedsMany
 
         # Builder class for embeds_many associations.
-        #
-        # @since 7.0
         module Buildable
           include Threaded::Lifecycle
 
@@ -18,17 +18,20 @@ module Mongoid
           #   Builder.new(meta, attrs).build
           #
           # @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 Not used in this context.
+          # @param [ Hash ] selected_fields Fields which were retrieved via
+          #   #only. If selected_fields are specified, fields not listed in it
+          #   will not be accessible in the built documents.
           #
           # @return [ Array<Document ] The documents.
-          def build(base, object, type = nil)
+          def build(base, object, type = nil, selected_fields = nil)
             return [] if object.blank?
             return object if object.first.is_a?(Document)
             docs = []
             object.each do |attrs|
               if _loading? && base.persisted?
-                docs.push(Factory.from_db(klass, attrs))
+                docs.push(Factory.from_db(klass, attrs, nil, selected_fields))
               else
                 docs.push(Factory.build(klass, attrs))
               end

data/lib/mongoid/association/embedded/embeds_many/proxy.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'mongoid/association/embedded/batchable'
 
 module Mongoid
@@ -8,7 +10,7 @@ module Mongoid
         class Proxy < Association::Many
           include Batchable
 
-          # 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.
@@ -30,19 +32,17 @@ module Mongoid
 
           alias :push :<<
 
-          # Get this relation as as its representation in the database.
+          # Get this association as as its representation in the database.
           #
-          # @example Convert the relation to an attributes hash.
+          # @example Convert the association to an attributes hash.
           #   person.addresses.as_document
           #
-          # @return [ Array<Hash> ] The relation as stored in the db.
-          #
-          # @since 2.0.0.rc.1
+          # @return [ Array<Hash> ] The association as stored in the db.
           def as_document
             as_attributes.collect { |attrs| BSON::Document.new(attrs) }
           end
 
-          # 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.
@@ -51,17 +51,15 @@ module Mongoid
           # @param [ Array<Document> ] docs The docs to add.
           #
           # @return [ Array<Document> ] The documents.
-          #
-          # @since 2.4.0
           def concat(docs)
             batch_insert(docs) unless docs.empty?
             self
           end
 
-          # Builds a new document in the relation and appends it to the target.
+          # Builds a new document in the association and appends it to the target.
           # Takes an optional type if you want to specify a subclass.
           #
-          # @example Build a new document on the relation.
+          # @example Build a new document on the association.
           #   person.people.build(:name => "Bozo")
           #
           # @param [ Hash ] attributes The attributes to build the document with.
@@ -74,19 +72,26 @@ module Mongoid
             doc.apply_post_processed_defaults
             yield(doc) if block_given?
             doc.run_callbacks(:build) { doc }
-            _base._reset_memoized_children!
+            _base._reset_memoized_descendants!
             doc
           end
 
           alias :new :build
 
-          # Clear the relation. Will delete the documents from the db if they are
-          # already persisted.
+          # Clear the association. Will delete the documents from the db
+          # if they are already persisted.
           #
-          # @example Clear the relation.
+          # If the host document is not persisted but its _id matches a
+          # persisted document, calling #clear on an association will remove
+          # the association's documents from the database even though the
+          # set of documents in the application (as loaded in the host)
+          # is different from what is in the database, and the host may
+          # not contain any persisted documents in the association either.
+          #
+          # @example Clear the association.
           #   person.addresses.clear
           #
-          # @return [ self ] The empty relation.
+          # @return [ self ] The empty association.
           def clear
             batch_clear(_target.dup)
             self
@@ -97,26 +102,38 @@ module Mongoid
           #
           # Use #size if you want the total number of documents.
           #
+          # If args or block are present, #count will delegate to the
+          # #count method on +target+ and will include both persisted
+          # and non-persisted documents.
+          #
           # @example Get the count of persisted documents.
           #   person.addresses.count
           #
+          # @example Get the count of all documents matching a block.
+          #   person.addresses.count { |a| a.country == "FR" }
+          #
+          # @example Use #persisted? inside block to count persisted documents.
+          #   person.addresses.count { |a| a.persisted? && a.country == "FR" }
+          #
+          # @param [ Object, Array<Object> ] args Args to delegate to the target.
+          #
           # @return [ Integer ] The total number of persisted embedded docs, as
           #   flagged by the #persisted? method.
-          def count
+          def count(*args, &block)
+            return _target.count(*args, &block) if args.any? || block
+
             _target.select { |doc| doc.persisted? }.size
           end
 
           # Delete the supplied document from the target. This method is proxied
           # in order to reindex the array after the operation occurs.
           #
-          # @example Delete the document from the relation.
+          # @example Delete the document from the association.
           #   person.addresses.delete(address)
           #
           # @param [ Document ] document The document to be deleted.
           #
           # @return [ Document, nil ] The deleted document or nil if nothing deleted.
-          #
-          # @since 2.0.0.rc.1
           def delete(document)
             execute_callback :before_remove, document
             doc = _target.delete_one(document)
@@ -136,10 +153,10 @@ module Mongoid
 
           # Delete all the documents in the association without running callbacks.
           #
-          # @example Delete all documents from the relation.
+          # @example Delete all documents from the association.
           #   person.addresses.delete_all
           #
-          # @example Conditionally delete documents from the relation.
+          # @example Conditionally delete documents from the association.
           #   person.addresses.delete_all({ :street => "Bond" })
           #
           # @param [ Hash ] conditions Conditions on which documents to delete.
@@ -156,10 +173,8 @@ module Mongoid
           #     doc.state == "GA"
           #   end
           #
-          # @return [ Many, Enumerator ] The relation or an enumerator if no
+          # @return [ Many, Enumerator ] The association or an enumerator if no
           #   block was provided.
-          #
-          # @since 3.1.0
           def delete_if
             if block_given?
               dup_target = _target.dup
@@ -174,10 +189,10 @@ module Mongoid
 
           # Destroy all the documents in the association whilst running callbacks.
           #
-          # @example Destroy all documents from the relation.
+          # @example Destroy all documents from the association.
           #   person.addresses.destroy_all
           #
-          # @example Conditionally destroy documents from the relation.
+          # @example Conditionally destroy documents from the association.
           #   person.addresses.destroy_all({ :street => "Bond" })
           #
           # @param [ Hash ] conditions Conditions on which documents to destroy.
@@ -187,7 +202,7 @@ module Mongoid
             remove_all(conditions, :destroy)
           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?
@@ -200,26 +215,38 @@ module Mongoid
           # Finds a document in this association through several different
           # methods.
           #
+          # 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 a document by its id.
           #   person.addresses.find(BSON::ObjectId.new)
           #
           # @example Find documents for multiple ids.
           #   person.addresses.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
           #
+          # @example Finds the first matching document using a block.
+          #   person.addresses.find { |addr| addr.state == 'CA' }
+          #
           # @param [ Array<Object> ] args Various arguments.
+          # @param [ Proc ] block Optional block to pass.
           #
-          # @return [ Array<Document>, Document ] A single or multiple documents.
-          def find(*args)
-            criteria.find(*args)
+          # @return [ Document | Array<Document> | nil ] A document or matching documents.
+          def find(*args, &block)
+            criteria.find(*args, &block)
           end
 
-          # Instantiate a new embeds_many relation.
+          # Instantiate a new embeds_many association.
           #
-          # @example Create the new relation.
+          # @example Create the new association.
           #   Many.new(person, addresses, association)
           #
-          # @param [ Document ] base The document this relation hangs off of.
-          # @param [ Array<Document> ] target The child documents of the relation.
+          # @param [ Document ] base The document this association hangs off of.
+          # @param [ Array<Document> ] target The child documents of the association.
           # @param [ Association ] association The association metadata
           #
           # @return [ Many ] The proxy.
@@ -234,19 +261,17 @@ module Mongoid
             end
           end
 
-          # Get all the documents in the relation that are loaded into memory.
+          # Get all the documents in the association that are loaded into memory.
           #
           # @example Get the in memory documents.
           #   relation.in_memory
           #
           # @return [ Array<Document> ] The documents in memory.
-          #
-          # @since 2.1.0
           def in_memory
             _target
           end
 
-          # Pop documents off the relation. This can be a single document or
+          # Pop documents off the association. This can be a single document or
           # multiples, and will automatically persist the changes.
           #
           # @example Pop a single document.
@@ -259,8 +284,6 @@ module Mongoid
           #   provided.
           #
           # @return [ Document, Array<Document> ] The popped document(s).
-          #
-          # @since 3.0.0
           def pop(count = nil)
             if count
               if docs = _target[_target.size - count, _target.size]
@@ -271,31 +294,50 @@ module Mongoid
             end
           end
 
+          # Shift documents off the association. This can be a single document or
+          # multiples, and will automatically persist the changes.
+          #
+          # @example Shift a single document.
+          #   relation.shift
+          #
+          # @example Shift multiple documents.
+          #   relation.shift(3)
+          #
+          # @param [ Integer ] count The number of documents to shift, or 1 if not
+          #   provided.
+          #
+          # @return [ Document, Array<Document> ] The shifted document(s).
+          def shift(count = nil)
+            if count
+              if _target.size > 0 && docs = _target[0, count]
+                docs.each { |doc| delete(doc) }
+              end
+            else
+              delete(_target[0])
+            end
+          end
+
           # Substitutes the supplied target documents for the existing documents
           # in the relation.
           #
-          # @example Substitute the relation's target.
+          # @example Substitute the association's target.
           #   person.addresses.substitute([ address ])
           #
           # @param [ Array<Document> ] docs The replacement docs.
           #
-          # @return [ Many ] The proxied relation.
-          #
-          # @since 2.0.0.rc.1
+          # @return [ Many ] The proxied association.
           def substitute(docs)
             batch_replace(docs)
             self
           end
 
-          # Return the relation with all previous scoping removed. This is the
+          # Return the association with all previous scoping removed. This is the
           # exact representation of the docs in the database.
           #
           # @example Get the unscoped documents.
           #   person.addresses.unscoped
           #
-          # @return [ Criteria ] The unscoped relation.
-          #
-          # @since 2.4.0
+          # @return [ Criteria ] The unscoped association.
           def unscoped
             criterion = klass.unscoped
             criterion.embedded = true
@@ -306,7 +348,7 @@ module Mongoid
           private
 
           def object_already_related?(document)
-            _target.any? { |existing| existing.id && existing === document }
+            _target.any? { |existing| existing._id && existing === document }
           end
 
           # Appends the document to the target array, updating the index on the
@@ -316,8 +358,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)
             execute_callback :before_add, document
             unless object_already_related?(document)
@@ -329,27 +369,22 @@ module Mongoid
             execute_callback :after_add, document
           end
 
-          # Instantiate the binding associated with this relation.
+          # Instantiate the binding associated with this association.
           #
           # @example Create the binding.
           #   relation.binding([ address ])
           #
           # @return [ Binding ] The many binding.
-          #
-          # @since 2.0.0.rc.1
           def binding
             Binding.new(_base, _target, _association)
           end
 
-          # Returns the "#{criteria}"# object for the target class with its documents set
-          # to target.
-          #
-          # @example Get a criteria for the relation.
-          #   relation.criteria
+          # Returns the +Criteria+ object for the target class with its
+          # documents set to the list of target documents in the association.
           #
           # @return [ Criteria ] A new criteria.
           def criteria
-            @criteria ||= _association.criteria(_base, _target)
+            _association.criteria(_base, _target)
           end
 
           # Deletes one document from the target and unscoped.
@@ -360,23 +395,19 @@ module Mongoid
           #   relation.delete_one(doc)
           #
           # @param [ Document ] document The document to delete.
-          #
-          # @since 2.4.7
           def delete_one(document)
             _target.delete_one(document)
             _unscoped.delete_one(document)
             reindex
           end
 
-          # Integrate the document into the relation. will set its metadata and
+          # Integrate the document into the association. will set its metadata and
           # attempt to bind the inverse.
           #
           # @example Integrate the document.
           #   relation.integrate(document)
           #
           # @param [ Document ] document The document to integrate.
-          #
-          # @since 2.1.0
           def integrate(document)
             characterize_one(document)
             bind_one(document)
@@ -392,21 +423,19 @@ module Mongoid
           # @param [ Proc ] block Optional block to pass.
           #
           # @return [ Criteria, Object ] A Criteria or return value from the target.
-          def method_missing(name, *args, &block)
+          ruby2_keywords def method_missing(name, *args, &block)
             return super if _target.respond_to?(name)
             klass.send(:with_scope, criteria) do
               criteria.public_send(name, *args, &block)
             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.
-          #
-          # @since 2.1.0
+          # @return [ true, false ] If the association is persistable.
           def persistable?
             _base.persisted? && !_binding?
           end
@@ -415,18 +444,16 @@ module Mongoid
           # operations on the proxied target directly and the indices need to
           # match that on the database side.
           #
-          # @example Reindex the relation.
+          # @example Reindex the association.
           #   person.addresses.reindex
-          #
-          # @since 2.0.0.rc.1
           def reindex
             _unscoped.each_with_index do |doc, index|
               doc._index = index
             end
           end
 
-          # Apply the association ordering or the default scoping to the provided
-          # documents.
+          # Apply the association ordering and default scoping (defined on
+          # association's target class) to the provided documents.
           #
           # @example Apply scoping.
           #   person.addresses.scope(target)
@@ -434,20 +461,21 @@ module Mongoid
           # @param [ Array<Document> ] docs The documents to scope.
           #
           # @return [ Array<Document> ] The scoped docs.
-          #
-          # @since 2.4.0
           def scope(docs)
-            return docs unless _association.order || _association.klass.default_scoping?
+            unless _association.order || _association.klass.default_scoping?
+              return docs
+            end
+
             crit = _association.klass.order_by(_association.order)
             crit.embedded = true
             crit.documents = docs
             crit.entries
           end
 
-          # Remove all documents from the relation, either with a delete or a
+          # Remove all documents from the association, either with a delete or a
           # destroy depending on what this was called through.
           #
-          # @example Destroy documents from the relation.
+          # @example Destroy documents from the association.
           #   relation.remove_all({ :num => 1 }, true)
           #
           # @param [ Hash ] conditions Conditions to filter by.
@@ -467,8 +495,6 @@ module Mongoid
           #   relation._unscoped
           #
           # @return [ Array<Document> ] The unscoped documents.
-          #
-          # @since 2.4.0
           def _unscoped
             @_unscoped ||= []
           end
@@ -481,8 +507,6 @@ module Mongoid
           # @param [ Array<Document> ] docs The documents.
           #
           # @return [ Array<Document ] The unscoped docs.
-          #
-          # @since 2.4.0
           def _unscoped=(docs)
             @_unscoped = docs
           end
@@ -497,15 +521,13 @@ module Mongoid
 
           class << self
 
-            # 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 true.
             #
-            # @example Is the relation embedded?
+            # @example Is the association embedded?
             #   Association::Embedded::EmbedsMany.embedded?
             #
             # @return [ true ] true.
-            #
-            # @since 2.0.0.rc.1
             def embedded?
               true
             end
@@ -516,8 +538,6 @@ module Mongoid
             #   Association::Embedded::EmbedsMany.foreign_key_suffix
             #
             # @return [ nil ] nil.
-            #
-            # @since 3.0.0
             def foreign_key_suffix
               nil
             end
@@ -526,4 +546,4 @@ module Mongoid
       end
     end
   end
-end
+end