mongoid 6.4.4 → 7.5.1

data/lib/mongoid/association/macros.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+
+    # This module contains the core macros for defining associations between
+    # documents. They can be either embedded or referenced.
+    module Macros
+      extend ActiveSupport::Concern
+
+      included do
+        class_attribute :embedded, instance_reader: false
+        class_attribute :embedded_relations
+        class_attribute :relations
+
+        # A hash that maps aliases to their associations. This hash maps the
+        # associations "in database name" to its "in code" name. This is used when
+        # associations specify the `store_as` option, or on a referenced association.
+        # On a referenced association, this is used to map the foreign key to
+        # the association's name. For example, if we had the following
+        # relationship:
+        #
+        #   User has_many Accounts
+        #
+        # User will have an entry in the aliased associations hash:
+        #
+        #   account_ids => accounts
+        #
+        # Note that on the belongs_to associations, the mapping from
+        # foreign key => name is not in the aliased_associations hash, but a
+        # mapping from name => foreign key is in the aliased_fields hash.
+        #
+        # @return [ Hash<String, String> ] The aliased associations hash.
+        #
+        # @api private
+        class_attribute :aliased_associations
+        self.embedded = false
+        self.embedded_relations = BSON::Document.new
+        self.relations = BSON::Document.new
+        self.aliased_associations = {}
+      end
+
+      # This is convenience for libraries still on the old API.
+      #
+      # @example Get the associations.
+      #   person.associations
+      #
+      # @return [ Hash ] The associations.
+      def associations
+        self.relations
+      end
+
+      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
+        # persistence methods on the child object will cause a save to fail.
+        #
+        # @example Define the association.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_many :addresses
+        #   end
+        #
+        #   class Address
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embedded_in(name, options = {}, &block)
+          define_association!(__method__, name, options, &block)
+        end
+
+        # Adds the association from a parent document to its children. The name
+        # of the association needs to be a pluralized form of the child class
+        # name.
+        #
+        # @example Define the association.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_many :addresses
+        #   end
+        #
+        #   class Address
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embeds_many(name, options = {}, &block)
+          define_association!(__method__, name, options, &block)
+        end
+
+        # Adds the association from a parent document to its child. The name
+        # of the association needs to be a singular form of the child class
+        # name.
+        #
+        # @example Define the association.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     embeds_one :name
+        #   end
+        #
+        #   class Name
+        #     include Mongoid::Document
+        #     embedded_in :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def embeds_one(name, options = {}, &block)
+          define_association!(__method__, name, options, &block)
+        end
+
+        # Adds a referenced association from the child Document to a Document
+        # in another database or collection.
+        #
+        # @example Define the association.
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     belongs_to :person
+        #   end
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     has_one :game
+        #   end
+        #
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def belongs_to(name, options = {}, &block)
+          define_association!(__method__, name, options, &block)
+        end
+
+        # Adds a referenced association from a parent Document to many
+        # Documents in another database or collection.
+        #
+        # @example Define the association.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     has_many :posts
+        #   end
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     belongs_to :person
+        #   end
+        #
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def has_many(name, options = {}, &block)
+          define_association!(__method__, name, options, &block)
+        end
+
+        # Adds a referenced many-to-many association between many of this
+        # Document and many of another Document.
+        #
+        # @example Define the association.
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     has_and_belongs_to_many :preferences
+        #   end
+        #
+        #   class Preference
+        #     include Mongoid::Document
+        #     has_and_belongs_to_many :people
+        #   end
+        #
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def has_and_belongs_to_many(name, options = {}, &block)
+          define_association!(__method__, name, options, &block)
+        end
+
+        # Adds a referenced association from the child Document to a Document
+        # in another database or collection.
+        #
+        # @example Define the association.
+        #
+        #   class Game
+        #     include Mongoid::Document
+        #     belongs_to :person
+        #   end
+        #
+        #   class Person
+        #     include Mongoid::Document
+        #     has_one :game
+        #   end
+        #
+        # @param [ Symbol ] name The name of the association.
+        # @param [ Hash ] options The association options.
+        # @param [ Proc ] block Optional block for defining extensions.
+        def has_one(name, options = {}, &block)
+          define_association!(__method__, name, options, &block)
+        end
+
+        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)
+            if assoc.respond_to?(:store_as) && assoc.store_as != name
+              self.aliased_associations[assoc.store_as] = name
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/association/many.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+
+    # This is the superclass for all many to one and many to many association
+    # proxies.
+    class Many < Association::Proxy
+      extend Forwardable
+      include ::Enumerable
+
+      def_delegators :criteria, :avg, :max, :min, :sum
+      def_delegators :_target, :length, :size, :any?
+
+      # Is the association empty?
+      #
+      # @example Is the association empty??
+      #   person.addresses.blank?
+      #
+      # @return [ true, false ] If the association is empty or not.
+      def blank?
+        !any?
+      end
+
+      # Creates a new document on the references many association. This will
+      # save the document if the parent has been persisted.
+      #
+      # @example Create and save the new document.
+      #   person.posts.create(:text => "Testing")
+      #
+      #
+      # @param [ Hash ] attributes The attributes to create with.
+      # @param [ Class ] type The optional type of document to create.
+      #
+      # @return [ Document ] The newly created document.
+      def create(attributes = nil, type = nil, &block)
+        if attributes.is_a?(::Array)
+          attributes.map { |attrs| create(attrs, type, &block) }
+        else
+          doc = build(attributes, type, &block)
+          _base.persisted? ? doc.save : raise_unsaved(doc)
+          doc
+        end
+      end
+
+      # Creates a new document on the references many association. This will
+      # save the document if the parent has been persisted and will raise an
+      # error if validation fails.
+      #
+      # @example Create and save the new document.
+      #   person.posts.create!(:text => "Testing")
+      #
+      # @param [ Hash ] attributes The attributes to create with.
+      # @param [ Class ] type The optional type of document to create.
+      #
+      # @raise [ Errors::Validations ] If validation failed.
+      #
+      # @return [ Document ] The newly created document.
+      def create!(attributes = nil, type = nil, &block)
+        if attributes.is_a?(::Array)
+          attributes.map { |attrs| create!(attrs, type, &block) }
+        else
+          doc = build(attributes, type, &block)
+          _base.persisted? ? doc.save! : raise_unsaved(doc)
+          doc
+        end
+      end
+
+      # Find the first document given the conditions, or creates a new document
+      # with the conditions that were supplied.
+      #
+      # @example Find or create.
+      #   person.posts.find_or_create_by(:title => "Testing")
+      #
+      #  @param [ Hash ] attrs The attributes to search or create with.
+      #  @param [ Class ] type The optional type of document to create.
+      #
+      # @return [ Document ] An existing document or newly created one.
+      def find_or_create_by(attrs = {}, type = nil, &block)
+        find_or(:create, attrs, type, &block)
+      end
+
+      # Find the first document given the conditions, or creates a new document
+      # with the conditions that were supplied. This will raise an error if validation fails.
+      #
+      # @example Find or create.
+      #   person.posts.find_or_create_by!(:title => "Testing")
+      #
+      # @param [ Hash ] attrs The attributes to search or create with.
+      # @param [ Class ] type The optional type of document to create.
+      #
+      # @raise [ Errors::Validations ] If validation failed.
+      #
+      # @return [ Document ] An existing document or newly created one.
+      def find_or_create_by!(attrs = {}, type = nil, &block)
+        find_or(:create!, attrs, type, &block)
+      end
+
+      # Find the first +Document+ given the conditions, or instantiates a new document
+      # with the conditions that were supplied
+      #
+      # @example Find or initialize.
+      #   person.posts.find_or_initialize_by(:title => "Test")
+      #
+      # @param [ Hash ] attrs The attributes to search or initialize with.
+      # @param [ Class ] type The optional subclass to build.
+      #
+      # @return [ Document ] An existing document or newly instantiated one.
+      def find_or_initialize_by(attrs = {}, type = nil, &block)
+        find_or(:build, attrs, type, &block)
+      end
+
+      # This proxy can never be nil.
+      #
+      # @example Is the proxy nil?
+      #   relation.nil?
+      #
+      # @return [ false ] Always false.
+      def nil?
+        false
+      end
+
+      # Since method_missing is overridden we should override this as well.
+      #
+      # @example Does the proxy respond to the method?
+      #   relation.respond_to?(:name)
+      #
+      # @param [ Symbol ] name The method name.
+      # @param [ true, false ] include_private Whether to include private methods.
+      #
+      # @return [ true, false ] If the proxy responds to the method.
+      def respond_to?(name, include_private = false)
+        [].respond_to?(name, include_private) ||
+          klass.respond_to?(name, include_private) || super
+      end
+
+      # This is public access to the association's criteria.
+      #
+      # @example Get the scoped association.
+      #   relation.scoped
+      #
+      # @return [ Criteria ] The scoped criteria.
+      def scoped
+        criteria
+      end
+
+      # Gets the document as a serializable hash, used by ActiveModel's JSON and
+      # XML serializers. This override is just to be able to pass the :include
+      # and :except options to get associations in the hash.
+      #
+      # @example Get the serializable hash.
+      #   relation.serializable_hash
+      #
+      # @param [ Hash ] options The options to pass.
+      #
+      # @option options [ Symbol ] :include What associations to include
+      # @option options [ Symbol ] :only Limit the fields to only these.
+      # @option options [ Symbol ] :except Dont include these fields.
+      #
+      # @return [ Hash ] The documents, ready to be serialized.
+      def serializable_hash(options = {})
+        _target.map { |document| document.serializable_hash(options) }
+      end
+
+      # Get a criteria for the embedded documents without the default scoping
+      # applied.
+      #
+      # @example Get the unscoped criteria.
+      #   person.addresses.unscoped
+      #
+      # @return [ Criteria ] The unscoped criteria.
+      def unscoped
+        criteria.unscoped
+      end
+
+      private
+
+      def _session
+        _base.send(:_session)
+      end
+
+      # Find the first object given the supplied attributes or create/initialize it.
+      #
+      # @example Find or create|initialize.
+      #   person.addresses.find_or(:create, :street => "Bond")
+      #
+      #   @param [ Symbol ] method The method name, create or new.
+      #   @param [ Hash ] attrs The attributes to search or build with.
+      #   @param [ Class ] type The optional subclass to build.
+      #
+      # @return [ Document ] A matching document or a new/created one.
+      def find_or(method, attrs = {}, type = nil, &block)
+        attrs[klass.discriminator_key] = type.discriminator_value if type
+        where(attrs).first || send(method, attrs, type, &block)
+      end
+    end
+  end
+end

data/lib/mongoid/association/marshalable.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+    module Marshalable
+
+      # Provides the data needed to Marshal.dump an association proxy.
+      #
+      # @example Dump the proxy.
+      #   Marshal.dump(proxy)
+      #
+      # @return [ Array<Object> ] The dumped data.
+      def marshal_dump
+        [ _base, _target, _association ]
+      end
+
+      # Takes the provided data and sets it back on the proxy.
+      #
+      # @example Load the proxy.
+      #   Marshal.load(proxy)
+      #
+      # @param [ Array<Object> ] data The data to set on the proxy.
+      #
+      # @return [ Array<Object> ] The loaded data.
+      def marshal_load(data)
+        @_base, @_target, @_association = data
+        extend_proxy(_association.extension) if _association.extension
+      end
+    end
+  end
+end

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

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Association
+    module Nested
+      class Many
+        include Buildable
+
+        # Builds the association depending on the attributes and the options
+        # passed to the macro.
+        #
+        # This attempts to perform 3 operations, either one of an update of
+        # the existing association, a replacement of the association with a new
+        # document, or a removal of the association.
+        #
+        # @example Build the nested attrs.
+        #   many.build(person)
+        #
+        # @param [ Document ] parent The parent document of the association.
+        # @param [ Hash ] options The options.
+        #
+        # @return [ Array ] The attributes.
+        def build(parent, options = {})
+          @existing = parent.send(association.name)
+          if over_limit?(attributes)
+            raise Errors::TooManyNestedAttributeRecords.new(existing, options[:limit])
+          end
+          attributes.each do |attrs|
+            if attrs.is_a?(::Hash)
+              process_attributes(parent, attrs.with_indifferent_access)
+            else
+              process_attributes(parent, attrs[1].with_indifferent_access)
+            end
+          end
+        end
+
+        # Create the new builder for nested attributes on one-to-many
+        # associations.
+        #
+        # @example Initialize the builder.
+        #   Many.new(association, attributes, options)
+        #
+        # @param [ Association ] 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 = {})
+          if attributes.respond_to?(:with_indifferent_access)
+            @attributes = attributes.with_indifferent_access.sort do |a, b|
+              a[0].to_i <=> b[0].to_i
+            end
+          else
+            @attributes = attributes
+          end
+          @association = association
+          @options = options
+          @class_name = options[:class_name] ? options[:class_name].constantize : association.klass
+        end
+
+        private
+
+        # Can the existing association potentially be deleted?
+        #
+        # @example Is the document destroyable?
+        #   destroyable?({ :_destroy => "1" })
+        #
+        # @param [ Hash ] attributes The attributes to pull the flag from.
+        #
+        # @return [ true, false ] If the association can potentially be deleted.
+        def destroyable?(attributes)
+          destroy = attributes.delete(:_destroy)
+          Nested::DESTROY_FLAGS.include?(destroy) && allow_destroy?
+        end
+
+        # Are the supplied attributes of greater number than the supplied
+        # limit?
+        #
+        # @example Are we over the set limit?
+        #   builder.over_limit?({ "street" => "Bond" })
+        #
+        # @param [ Hash ] attributes The attributes being set.
+        #
+        # @return [ true, false ] If the attributes exceed the limit.
+        def over_limit?(attributes)
+          limit = options[:limit]
+          limit ? attributes.size > limit : false
+        end
+
+        # Process each set of attributes one at a time for each potential
+        # new, existing, or ignored document.
+        #
+        # @api private
+        #
+        # @example Process the attributes
+        #   builder.process_attributes({ "id" => 1, "street" => "Bond" })
+        #
+        # @param [ Document ] parent The parent document.
+        # @param [ Hash ] attrs The single document attributes to process.
+        def process_attributes(parent, attrs)
+          return if reject?(parent, attrs)
+          if id = attrs.extract_id
+            update_nested_relation(parent, id, attrs)
+          else
+            existing.push(Factory.build(@class_name, attrs)) unless destroyable?(attrs)
+          end
+        end
+
+        # Destroy the child document, needs to do some checking for embedded
+        # associations and delay the destroy in case parent validation fails.
+        #
+        # @api private
+        #
+        # @example Destroy the child.
+        #   builder.destroy(parent, relation, doc)
+        #
+        # @param [ Document ] parent The parent document.
+        # @param [ Proxy ] relation The association proxy.
+        # @param [ Document ] doc The doc to destroy.
+        def destroy(parent, relation, doc)
+          doc.flagged_for_destroy = true
+          if !doc.embedded? || parent.new_record?
+            destroy_document(relation, doc)
+          else
+            parent.flagged_destroys.push(-> { destroy_document(relation, doc) })
+          end
+        end
+
+        # Destroy the document.
+        #
+        # @api private
+        #
+        # @example Destroy the document.
+        #   builder.destroy_document(relation, doc)
+        #
+        # @param [ Proxy ] relation The association proxy.
+        # @param [ Document ] doc The document to delete.
+        def destroy_document(relation, doc)
+          relation.delete(doc)
+          doc.destroy unless doc.embedded? || doc.destroyed?
+        end
+
+        # Update the document.
+        #
+        # @api private
+        #
+        # @example Update the document.
+        #   builder.update_document(doc, {}, options)
+        #
+        # @param [ Document ] doc The document to update.
+        # @param [ Hash ] attrs The attributes.
+        def update_document(doc, attrs)
+          attrs.delete_id
+          if association.embedded?
+            doc.assign_attributes(attrs)
+          else
+            doc.update_attributes(attrs)
+          end
+        end
+
+        # Update nested association.
+        #
+        # @api private
+        #
+        # @example Update nested association.
+        #   builder.update_nested_relation(parent, id, attrs)
+        #
+        # @param [ Document ] parent The parent document.
+        # @param [ String, BSON::ObjectId ] id of the related document.
+        # @param [ Hash ] attrs The single document attributes to process.
+        def update_nested_relation(parent, id, attrs)
+          first = existing.first
+          converted = first ? convert_id(first.class, id) : id
+
+          if existing.where(_id: converted).exists?
+            # document exists in association
+            doc = existing.find(converted)
+            if destroyable?(attrs)
+              destroy(parent, existing, doc)
+            else
+              update_document(doc, attrs)
+            end
+          else
+            # push existing document to association
+            doc = association.klass.unscoped.find(converted)
+            update_document(doc, attrs)
+            existing.push(doc) unless destroyable?(attrs)
+          end
+        end
+      end
+    end
+  end
+end