mongoid 6.4.4 → 7.1.7

data/lib/mongoid/association/embedded.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+require 'mongoid/association/embedded/cyclic'
+require 'mongoid/association/embedded/embedded_in'
+require 'mongoid/association/embedded/embeds_many'
+require 'mongoid/association/embedded/embeds_one'

data/lib/mongoid/association/macros.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+# encoding: utf-8
+
+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
+        self.embedded = false
+        self.embedded_relations = BSON::Document.new
+        self.relations = BSON::Document.new
+      end
+
+      # This is convenience for libraries still on the old API.
+      #
+      # @example Get the associations.
+      #   person.associations
+      #
+      # @return [ Hash ] The associations.
+      #
+      # @since 2.3.1
+      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.
+        #
+        # @since 2.0.0.rc.1
+        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)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/mongoid/{relations → association}/many.rb

@@ -1,41 +1,39 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
-  module Relations
+  module Association
 
-    # This is the superclass for all many to one and many to many relation
+    # This is the superclass for all many to one and many to many association
     # proxies.
-    class Many < Proxy
+    class Many < Association::Proxy
+      extend Forwardable
       include ::Enumerable
 
-      delegate :avg, :max, :min, :sum, to: :criteria
-      delegate :length, :size, to: :target
+      def_delegators :criteria, :avg, :max, :min, :sum
+      def_delegators :_target, :length, :size
 
-      # Is the relation empty?
+      # Is the association empty?
       #
-      # @example Is the relation empty??
+      # @example Is the association empty??
       #   person.addresses.blank?
       #
-      # @return [ true, false ] If the relation is empty or not.
+      # @return [ true, false ] If the association is empty or not.
       #
       # @since 2.1.0
       def blank?
         size == 0
       end
 
-      # Creates a new document on the references many relation. This will
+      # 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")
       #
-      # @overload create(attributes = nil, options = {}, type = nil)
-      #   @param [ Hash ] attributes The attributes to create with.
-      #   @param [ Hash ] options The scoped assignment options.
-      #   @param [ Class ] type The optional type of document to create.
       #
-      # @overload create(attributes = nil, type = nil)
-      #   @param [ Hash ] attributes The attributes to create with.
-      #   @param [ Class ] type The optional type of document to create.
+      # @param [ Hash ] attributes The attributes to create with.
+      # @param [ Class ] type The optional type of document to create.
       #
       # @return [ Document ] The newly created document.
       #
@@ -45,25 +43,20 @@ module Mongoid
           attributes.map { |attrs| create(attrs, type, &block) }
         else
           doc = build(attributes, type, &block)
-          base.persisted? ? doc.save : raise_unsaved(doc)
+          _base.persisted? ? doc.save : raise_unsaved(doc)
           doc
         end
       end
 
-      # Creates a new document on the references many relation. This will
+      # 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")
       #
-      # @overload create!(attributes = nil, options = {}, type = nil)
-      #   @param [ Hash ] attributes The attributes to create with.
-      #   @param [ Class ] type The optional type of document to create.
-      #
-      # @overload create!(attributes = nil, type = nil)
-      #   @param [ Hash ] attributes The attributes to create with.
-      #   @param [ Class ] type The optional type of document to create.
+      # @param [ Hash ] attributes The attributes to create with.
+      # @param [ Class ] type The optional type of document to create.
       #
       # @raise [ Errors::Validations ] If validation failed.
       #
@@ -75,7 +68,7 @@ module Mongoid
           attributes.map { |attrs| create!(attrs, type, &block) }
         else
           doc = build(attributes, type, &block)
-          base.persisted? ? doc.save! : raise_unsaved(doc)
+          _base.persisted? ? doc.save! : raise_unsaved(doc)
           doc
         end
       end
@@ -86,13 +79,8 @@ module Mongoid
       # @example Find or create.
       #   person.posts.find_or_create_by(:title => "Testing")
       #
-      # @overload find_or_create_by(attributes = nil, type = nil)
-      #   @param [ Hash ] attributes The attributes to search or create with.
-      #   @param [ Class ] type The optional type of document to create.
-      #
-      # @overload find_or_create_by(attributes = nil, type = nil)
-      #   @param [ Hash ] attributes The attributes to search or create with.
-      #   @param [ Class ] type The optional type of document to create.
+      #  @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)
@@ -105,13 +93,8 @@ module Mongoid
       # @example Find or create.
       #   person.posts.find_or_create_by!(:title => "Testing")
       #
-      # @overload find_or_create_by!(attributes = nil, type = nil)
-      #   @param [ Hash ] attributes The attributes to search or create with.
-      #   @param [ Class ] type The optional type of document to create.
-      #
-      # @overload find_or_create_by!(attributes = nil, type = nil)
-      #   @param [ Hash ] attributes The attributes to search or create with.
-      #   @param [ Class ] type The optional type of document to create.
+      # @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.
       #
@@ -126,13 +109,8 @@ module Mongoid
       # @example Find or initialize.
       #   person.posts.find_or_initialize_by(:title => "Test")
       #
-      # @overload find_or_initialize_by(attributes = {}, type = nil)
-      #   @param [ Hash ] attributes The attributes to search or initialize with.
-      #   @param [ Class ] type The optional subclass to build.
-      #
-      # @overload find_or_initialize_by(attributes = {}, type = nil)
-      #   @param [ Hash ] attributes The attributes to search or initialize with.
-      #   @param [ Class ] type The optional subclass to build.
+      # @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)
@@ -157,6 +135,7 @@ module Mongoid
       #   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.
       #
@@ -166,9 +145,9 @@ module Mongoid
           klass.respond_to?(name, include_private) || super
       end
 
-      # This is public access to the relation's criteria.
+      # This is public access to the association's criteria.
       #
-      # @example Get the scoped relation.
+      # @example Get the scoped association.
       #   relation.scoped
       #
       # @return [ Criteria ] The scoped criteria.
@@ -187,7 +166,7 @@ module Mongoid
       #
       # @param [ Hash ] options The options to pass.
       #
-      # @option options [ Symbol ] :include What relations to include
+      # @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.
       #
@@ -195,7 +174,7 @@ module Mongoid
       #
       # @since 2.0.0.rc.6
       def serializable_hash(options = {})
-        target.map { |document| document.serializable_hash(options) }
+        _target.map { |document| document.serializable_hash(options) }
       end
 
       # Get a criteria for the embedded documents without the default scoping
@@ -214,7 +193,7 @@ module Mongoid
       private
 
       def _session
-        base.send(:_session)
+        _base.send(:_session)
       end
 
       # Find the first object given the supplied attributes or create/initialize it.
@@ -222,14 +201,8 @@ module Mongoid
       # @example Find or create|initialize.
       #   person.addresses.find_or(:create, :street => "Bond")
       #
-      # @overload find_or(method, attributes = {}, type = nil)
-      #   @param [ Symbol ] method The method name, create or new.
-      #   @param [ Hash ] attributes The attributes to search or build with.
-      #   @param [ Class ] type The optional subclass to build.
-      #
-      # @overload find_or(attributes = {}, type = nil)
       #   @param [ Symbol ] method The method name, create or new.
-      #   @param [ Hash ] attributes The attributes to search or build with.
+      #   @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.

data/lib/mongoid/{relations → association}/marshalable.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
-  module Relations
+  module Association
     module Marshalable
 
-      # Provides the data needed to Marshal.dump a relation proxy.
+      # Provides the data needed to Marshal.dump an association proxy.
       #
       # @example Dump the proxy.
       #   Marshal.dump(proxy)
@@ -12,7 +14,7 @@ module Mongoid
       #
       # @since 3.0.15
       def marshal_dump
-        [ base, target, __metadata ]
+        [ _base, _target, _association ]
       end
 
       # Takes the provided data and sets it back on the proxy.
@@ -20,12 +22,14 @@ module Mongoid
       # @example Load the proxy.
       #   Marshal.load(proxy)
       #
+      # @param [ Array<Object> ] data The data to set on the proxy.
+      #
       # @return [ Array<Object> ] The loaded data.
       #
       # @since 3.0.15
       def marshal_load(data)
-        @base, @target, @__metadata = data
-        extend_proxy(__metadata.extension) if __metadata.extension?
+        @_base, @_target, @_association = data
+        extend_proxy(_association.extension) if _association.extension
       end
     end
   end