mongoid 7.4.3 → 8.0.7

data/lib/mongoid/criteria/queryable.rb

@@ -33,9 +33,10 @@ module Mongoid
       include Optional
 
       # @attribute [r] aliases The aliases.
-      # @attribute [r] driver The Mongo driver being used.
+      attr_reader :aliases
+
       # @attribute [r] serializers The serializers.
-      attr_reader :aliases, :driver, :serializers
+      attr_reader :serializers
 
       # Is this queryable equal to another object? Is true if the selector and
       # options are equal.
@@ -45,7 +46,7 @@ module Mongoid
       #
       # @param [ Object ] other The object to compare against.
       #
-      # @return [ true, false ] If the objects are equal.
+      # @return [ true | false ] If the objects are equal.
       def ==(other)
         return false unless other.is_a?(Queryable)
         selector == other.selector && options == other.options
@@ -59,11 +60,15 @@ module Mongoid
       #
       # @param [ Hash ] aliases The optional field aliases.
       # @param [ Hash ] serializers The optional field serializers.
+      # @param [ Hash ] associations The optional associations.
+      # @param [ Hash ] aliased_associations The optional aliased associations.
       # @param [ Symbol ] driver The driver being used.
-      def initialize(aliases = {}, serializers = {}, driver = :mongo)
-        @aliases, @driver, @serializers = aliases, driver.to_sym, serializers
-        @options = Options.new(aliases, serializers)
-        @selector = Selector.new(aliases, serializers)
+      #
+      # @api private
+      def initialize(aliases = {}, serializers = {}, associations = {}, aliased_associations = {})
+        @aliases, @serializers = aliases, serializers
+        @options = Options.new(aliases, serializers, associations, aliased_associations)
+        @selector = Selector.new(aliases, serializers, associations, aliased_associations)
         @pipeline = Pipeline.new(aliases)
         @aggregating = nil
         yield(self) if block_given?

data/lib/mongoid/criteria/scopable.rb

@@ -83,7 +83,7 @@ module Mongoid
       # @example Is the default scope applied?
       #   criteria.scoped?
       #
-      # @return [ true, false ] If the default scope is applied.
+      # @return [ true | false ] If the default scope is applied.
       def scoped?
         !!(defined?(@scoped) ? @scoped : nil)
       end
@@ -108,7 +108,7 @@ module Mongoid
       # @example Is the criteria unscoped?
       #   criteria.unscoped?
       #
-      # @return [ true, false ] If the criteria is force unscoped.
+      # @return [ true | false ] If the criteria is force unscoped.
       def unscoped?
         !!(defined?(@unscoped) ? @unscoped : nil)
       end

data/lib/mongoid/criteria/translator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Mongoid
+  class Criteria
+
+    # This is a helper module for translating atomic and composite
+    # Ruby values into corresponding query and option components.
+    # Originally implemented as patches to core classes, that approach
+    # has generally fallen into disfavor, as it bleeds too much into
+    # the public namespace.
+    #
+    # @api private
+    module Translator
+      extend self
+
+      # Converts the given value to a direction specification for use in
+      # sorting.
+      #
+      # @example Convert the value to a direction.
+      #   Translator.to_direction(:desc)
+      #   Translator.to_direction("1")
+      #   Translator.to_direction(-1)
+      #   Translator.to_direction(score: { "$meta": "textScore" })
+      #
+      # @param [ Hash | Numeric | String | Symbol ] value The value to convert.
+      #
+      # @return [ Hash | Numeric ] The direction.
+      def to_direction(value)
+        case value
+        when Hash then
+          value
+        when Numeric then
+          value
+        when String then
+          value =~ /desc/i ? -1 : 1
+        when Symbol then
+          to_direction(value.to_s)
+        else
+          raise ArgumentError, "cannot translate #{value.inspect} (#{value.class}) to a direction specification"
+        end
+      end
+    end
+
+  end
+end

data/lib/mongoid/criteria.rb

@@ -8,6 +8,7 @@ require "mongoid/criteria/modifiable"
 require "mongoid/criteria/queryable"
 require "mongoid/criteria/scopable"
 require "mongoid/criteria/options"
+require "mongoid/criteria/translator"
 
 module Mongoid
 
@@ -52,7 +53,7 @@ module Mongoid
     #
     # @param [ Object ] other The other +Enumerable+ or +Criteria+ to compare to.
     #
-    # @return [ true, false ] If the objects are equal.
+    # @return [ true | false ] If the objects are equal.
     def ==(other)
       return super if other.respond_to?(:selector)
       entries == other
@@ -73,6 +74,9 @@ module Mongoid
     # treated by Mongoid - the decision between delegating to +Findable+ vs
     # +Enumerable+ is made solely based on whether +find+ is passed a block.
     #
+    # @note Each argument can be an individual id, an array of ids or
+    #   a nested array. Each array will be flattened.
+    #
     # @example Finds a document by its _id, invokes Findable#find.
     #   critera.find("1234")
     #
@@ -85,6 +89,9 @@ module Mongoid
     # @example Tries to find a document whose _id is the stringification of the provided Proc, typically failing.
     #   enumerator = criteria.find(-> { "Default Band" })
     #
+    # @param [ Object | Array<Object> ] *args The ids.
+    # @param [ Proc ] block Optional block to pass.
+    #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
     #
     # @raise Errors::DocumentNotFound If the parameters were _id values and
@@ -112,31 +119,6 @@ module Mongoid
       entries.as_json(options)
     end
 
-    # Tells the criteria that the cursor that gets returned needs to be
-    # cached. This is so multiple iterations don't hit the database multiple
-    # times, however this is not advisable when working with large data sets
-    # as the entire results will get stored in memory.
-    #
-    # @example Flag the criteria as cached.
-    #   criteria.cache
-    #
-    # @return [ Criteria ] The cloned criteria.
-    def cache
-      crit = clone
-      crit.options.merge!(cache: true)
-      crit
-    end
-
-    # Will return true if the cache option has been set.
-    #
-    # @example Is the criteria cached?
-    #   criteria.cached?
-    #
-    # @return [ true, false ] If the criteria is flagged as cached.
-    def cached?
-      options[:cache] == true
-    end
-
     # Get the documents from the embedded criteria.
     #
     # @example Get the documents.
@@ -163,7 +145,7 @@ module Mongoid
     # @example Is the criteria for embedded documents?
     #   criteria.embedded?
     #
-    # @return [ true, false ] If the criteria is embedded.
+    # @return [ true | false ] If the criteria is embedded.
     def embedded?
       !!@embedded
     end
@@ -230,7 +212,7 @@ module Mongoid
       @klass = klass
       @embedded = nil
       @none = nil
-      klass ? super(klass.aliased_fields, klass.fields) : super({}, {})
+      klass ? super(klass.aliased_fields, klass.fields, klass.relations, klass.aliased_associations) : super({}, {}, {}, {})
     end
 
     # Merges another object with this +Criteria+ and returns a new criteria.
@@ -293,7 +275,7 @@ module Mongoid
     # @example Is the criteria a none criteria?
     #   criteria.empty_and_chainable?
     #
-    # @return [ true, false ] If the criteria is a none.
+    # @return [ true | false ] If the criteria is a none.
     def empty_and_chainable?
       !!@none
     end
@@ -351,9 +333,9 @@ module Mongoid
     #   crtiteria.respond_to?(:each)
     #
     # @param [ Symbol ] name The name of the class method on the +Document+.
-    # @param [ true, false ] include_private Whether to include privates.
+    # @param [ true | false ] include_private Whether to include privates.
     #
-    # @return [ true, false ] If the criteria responds to the method.
+    # @return [ true | false ] If the criteria responds to the method.
     def respond_to?(name, include_private = false)
       super || klass.respond_to?(name) || CHECK.respond_to?(name, include_private)
     end
@@ -404,7 +386,7 @@ module Mongoid
     # @example Add a javascript selection.
     #   criteria.where("this.name == 'syd'")
     #
-    # @param [ String, Hash ] expression The javascript or standard selection.
+    # @param [ String | Hash ] expression The javascript or standard selection.
     #
     # @raise [ UnsupportedJavascript ] If provided a string and the criteria
     #   is embedded.
@@ -430,7 +412,6 @@ module Mongoid
       super
     end
 
-
     # Get a version of this criteria without the options.
     #
     # @example Get the criteria without options.
@@ -536,7 +517,7 @@ module Mongoid
     # @example Add the type selection.
     #   criteria.merge_type_selection
     #
-    # @return [ true, false ] If type selection was added.
+    # @return [ true | false ] If type selection was added.
     def merge_type_selection
       selector.merge!(type_selection) if type_selectable?
     end
@@ -548,7 +529,7 @@ module Mongoid
     # @example If the criteria type selectable?
     #   criteria.type_selectable?
     #
-    # @return [ true, false ] If type selection should be added.
+    # @return [ true | false ] If type selection should be added.
     def type_selectable?
       klass.hereditary? &&
         !selector.keys.include?(self.discriminator_key) &&

data/lib/mongoid/deprecable.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "mongoid/deprecation"
+
+module Mongoid
+
+  # Adds ability to declare Mongoid-specific deprecations.
+  #
+  # @api private
+  module Deprecable
+
+    # Declares method(s) as deprecated.
+    #
+    # @example Deprecate a method.
+    #   Mongoid.deprecate(Cat, :meow); Cat.new.meow
+    #   #=> Mongoid.logger.warn("meow is deprecated and will be removed from Mongoid 8.0")
+    #
+    # @example Deprecate a method and declare the replacement method.
+    #   Mongoid.deprecate(Cat, meow: :speak); Cat.new.meow
+    #   #=> Mongoid.logger.warn("meow is deprecated and will be removed from Mongoid 8.0 (use speak instead)")
+    #
+    # @example Deprecate a method and give replacement instructions.
+    #   Mongoid.deprecate(Cat, meow: 'eat :catnip instead'); Cat.new.meow
+    #   #=> Mongoid.logger.warn("meow is deprecated and will be removed from Mongoid 8.0 (eat :catnip instead)")
+    #
+    # @param [ Module ] target_module The parent which contains the method.
+    # @param [ [ Symbol | Hash<Symbol, [ Symbol | String ]> ]... ] *method_descriptors
+    #   The methods to deprecate, with optional replacement instructions.
+    def deprecate(target_module, *method_descriptors)
+      @_deprecator ||= Mongoid::Deprecation.new
+      @_deprecator.deprecate_methods(target_module, *method_descriptors)
+    end
+  end
+end
+
+# Ensure Mongoid.deprecate can be used during initialization
+Mongoid.extend(Mongoid::Deprecable)

data/lib/mongoid/deprecation.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mongoid
+
+  # Utility class for logging deprecation warnings.
+  class Deprecation < ::ActiveSupport::Deprecation
+
+    @gem_name = 'Mongoid'
+
+    # Per change policy, deprecations will be removed in the next major version.
+    @deprecation_horizon = "#{Mongoid::VERSION.split('.').first.to_i + 1}.0".freeze
+
+    # Overrides default ActiveSupport::Deprecation behavior
+    # to use Mongoid's logger.
+    #
+    # @return Array<Proc> The deprecation behavior.
+    def behavior
+      @behavior ||= Array(->(*args) {
+        logger = Mongoid.logger
+        logger.warn(args[0])
+        logger.debug(args[1].join("\n  ")) if debug
+      })
+    end
+  end
+end

data/lib/mongoid/document.rb

@@ -56,7 +56,7 @@ module Mongoid
     # @example Check if frozen
     #   document.frozen?
     #
-    # @return [ true, false ] True if frozen, else false.
+    # @return [ true | false ] True if frozen, else false.
     def frozen?
       attributes.frozen?
     end
@@ -100,21 +100,8 @@ module Mongoid
     # @param [ Hash ] attrs The attributes to set up the document with.
     #
     # @return [ Document ] A new document.
-    def initialize(attrs = nil)
-      @__parent = nil
-      _building do
-        @new_record = true
-        @attributes ||= {}
-        apply_pre_processed_defaults
-        apply_default_scoping
-        process_attributes(attrs) do
-          yield(self) if block_given?
-        end
-        apply_post_processed_defaults
-        # @todo: #2586: Need to have access to parent document in these
-        #   callbacks.
-        run_callbacks(:initialize) unless _initialize_callbacks.empty?
-      end
+    def initialize(attrs = nil, &block)
+      construct_document(attrs, &block)
     end
 
     # Return the model name of the document.
@@ -137,16 +124,6 @@ module Mongoid
       (persisted? || destroyed?) ? [ _id.to_s ] : nil
     end
 
-    # Return an array with this +Document+ only in it.
-    #
-    # @example Return the document in an array.
-    #   document.to_a
-    #
-    # @return [ Array<Document> ] An array with the document as its only item.
-    def to_a
-      [ self ]
-    end
-
     # Return a hash of the entire document hierarchy from this document and
     # below. Used when the attributes are needed for everything and not just
     # the current document.
@@ -173,14 +150,14 @@ module Mongoid
     #
     # @param [ Hash ] options The options.
     #
-    # @option options [ true, false ] :compact (Deprecated) Whether to include fields
+    # @option options [ true | false ] :compact (Deprecated) Whether to include fields
     #   with nil values in the json document.
     #
     # @return [ Hash ] The document as json.
     def as_json(options = nil)
       rv = super
       if options && options[:compact]
-        Mongoid.logger.warn('#as_json :compact option is deprecated. Please call #compact on the returned Hash object instead.')
+        Mongoid::Warnings.warn_as_json_compact_deprecated
         rv = rv.compact
       end
       rv
@@ -228,6 +205,47 @@ module Mongoid
 
     private
 
+    # Does the construction of a document.
+    #
+    # @param [ Hash ] attrs The attributes to set up the document with.
+    # @param [ Hash ] options The options to use.
+    #
+    # @option options [ true | false ] :execute_callbacks Flag specifies
+    #   whether callbacks should be run.
+    #
+    # @return [ Document ] A new document.
+    #
+    # @note A Ruby 2.x bug prevents the options hash from being keyword
+    #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+    #   the options hash as keyword arguments.
+    #   See https://bugs.ruby-lang.org/issues/15753
+    #
+    # @api private
+    def construct_document(attrs = nil, options = {})
+      execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+
+      @__parent = nil
+      _building do
+        @new_record = true
+        @attributes ||= {}
+        apply_pre_processed_defaults
+        apply_default_scoping
+        process_attributes(attrs) do
+          yield(self) if block_given?
+        end
+        @attributes_before_type_cast = @attributes.merge(attributes_before_type_cast)
+
+        if execute_callbacks
+          apply_post_processed_defaults
+          run_callbacks(:initialize) unless _initialize_callbacks.empty?
+        else
+          pending_callbacks << :apply_post_processed_defaults
+          pending_callbacks << :initialize
+        end
+      end
+      self
+    end
+
     # Returns the logger
     #
     # @return [ Logger ] The configured logger or a default Logger instance.
@@ -245,6 +263,14 @@ module Mongoid
       @model_cache_key ||= self.class.model_name.cache_key
     end
 
+    # Returns a hash of the attributes.
+    #
+    # Note this method modifies the attributes hash that already exists on the
+    # class and returns it. This means that the hash returned by this method
+    # refers to the same hash as calling #attributes on the instance. See
+    # MONGOID-4476 for an explanation on how this is used.
+    #
+    # @return [ Hash ] The attributes hash.
     def as_attributes
       return attributes if frozen?
       embedded_relations.each_pair do |name, meta|
@@ -264,6 +290,20 @@ module Mongoid
 
     module ClassMethods
 
+      # Indicate whether callbacks should be invoked by default or not,
+      # within the block. Callbacks may always be explicitly invoked by passing
+      # `execute_callbacks: true` where available.
+      #
+      # @params execute_callbacks [ true | false ] Whether callbacks should be
+      #   suppressed or not.
+      def with_callbacks(execute_callbacks)
+        saved, Threaded.execute_callbacks =
+          Threaded.execute_callbacks?, execute_callbacks
+        yield
+      ensure
+        Threaded.execute_callbacks = saved
+      end
+
       # Instantiate a new object, only when loaded from the database or when
       # the attributes have already been typecast.
       #
@@ -273,20 +313,81 @@ module Mongoid
       # @param [ Hash ] attrs The hash of attributes to instantiate with.
       # @param [ Integer ] selected_fields The selected fields from the
       #   criteria.
+      # @param [ true | false ] execute_callbacks Flag specifies whether callbacks
+      #   should be run.
+      #
+      # @return [ Document ] A new document.
+      def instantiate(attrs = nil, selected_fields = nil, &block)
+        instantiate_document(attrs, selected_fields, &block)
+      end
+
+      # Instantiate the document.
+      #
+      # @param [ Hash ] attrs The hash of attributes to instantiate with.
+      # @param [ Integer ] selected_fields The selected fields from the
+      #   criteria.
+      # @param [ Hash ] options The options to use.
+      #
+      # @option options [ true | false ] :execute_callbacks Flag specifies
+      #   whether callbacks should be run.
       #
       # @return [ Document ] A new document.
-      def instantiate(attrs = nil, selected_fields = nil)
-        attributes = attrs || {}
+      #
+      # @note A Ruby 2.x bug prevents the options hash from being keyword
+      #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+      #   the options hash as keyword arguments.
+      #
+      # @api private
+      def instantiate_document(attrs = nil, selected_fields = nil, options = {})
+        execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+        attributes = if Mongoid.legacy_attributes
+          attrs
+        else
+          attrs&.to_h
+        end || {}
+
         doc = allocate
         doc.__selected_fields = selected_fields
         doc.instance_variable_set(:@attributes, attributes)
-        doc.apply_defaults
-        yield(doc) if block_given?
-        doc.run_callbacks(:find) unless doc._find_callbacks.empty?
-        doc.run_callbacks(:initialize) unless doc._initialize_callbacks.empty?
+        # TODO: remove the to_h when the legacy_attributes flag is removed.
+        # The to_h ensures that we don't accidentally make attributes_before_type_cast
+        # a BSON::Document.
+        doc.instance_variable_set(:@attributes_before_type_cast, attributes&.to_h.dup)
+
+        if execute_callbacks
+          doc.apply_defaults
+          yield(doc) if block_given?
+          doc.run_callbacks(:find) unless doc._find_callbacks.empty?
+          doc.run_callbacks(:initialize) unless doc._initialize_callbacks.empty?
+        else
+          yield(doc) if block_given?
+          doc.pending_callbacks += [:apply_defaults, :find, :initialize]
+        end
+
         doc
       end
 
+      # Allocates and constructs a document.
+      #
+      # @param [ Hash ] attrs The attributes to set up the document with.
+      # @param [ Hash ] options The options to use.
+      #
+      # @option options [ true | false ] :execute_callbacks Flag specifies
+      #   whether callbacks should be run.
+      #
+      # @note A Ruby 2.x bug prevents the options hash from being keyword
+      #   arguments. Once we drop support for Ruby 2.x, we can reimplement
+      #   the options hash as keyword arguments.
+      #   See https://bugs.ruby-lang.org/issues/15753
+      #
+      # @return [ Document ] A new document.
+      #
+      # @api private
+      def construct_document(attrs = nil, options = {})
+        execute_callbacks = options.fetch(:execute_callbacks, Threaded.execute_callbacks?)
+        with_callbacks(execute_callbacks) { new(attrs) }
+      end
+
       # Returns all types to query for when using this class as the base.
       #
       # @example Get the types.

data/lib/mongoid/equality.rb

@@ -26,9 +26,9 @@ module Mongoid
     # @example Compare for equality.
     #   document == other
     #
-    # @param [ Document, Object ] other The other object to compare with.
+    # @param [ Document | Object ] other The other object to compare with.
     #
-    # @return [ true, false ] True if the ids are equal, false if not.
+    # @return [ true | false ] True if the ids are equal, false if not.
     def ==(other)
       self.class == other.class &&
           attributes["_id"] == other.attributes["_id"]
@@ -39,9 +39,9 @@ module Mongoid
     # @example Compare the classes.
     #   document === other
     #
-    # @param [ Document, Object ] other The other object to compare with.
+    # @param [ Document | Object ] other The other object to compare with.
     #
-    # @return [ true, false ] True if the classes are equal, false if not.
+    # @return [ true | false ] True if the classes are equal, false if not.
     def ===(other)
       if Mongoid.legacy_triple_equals
         other.class == Class ? self.class === other : self == other
@@ -55,9 +55,9 @@ module Mongoid
     # @example Perform equality checking.
     #   document.eql?(other)
     #
-    # @param [ Document, Object ] other The object to check against.
+    # @param [ Document | Object ] other The object to check against.
     #
-    # @return [ true, false ] True if equal, false if not.
+    # @return [ true | false ] True if equal, false if not.
     def eql?(other)
       self == (other)
     end
@@ -68,9 +68,9 @@ module Mongoid
       # @example Compare the classes.
       #   document === other
       #
-      # @param [ Document, Object ] other The other object to compare with.
+      # @param [ Document | Object ] other The other object to compare with.
       #
-      # @return [ true, false ] True if the classes are equal, false if not.
+      # @return [ true | false ] True if the classes are equal, false if not.
       def ===(other)
         if Mongoid.legacy_triple_equals
           other.class == Class ? self <= other : other.is_a?(self)

data/lib/mongoid/errors/document_not_found.rb

@@ -19,23 +19,25 @@ module Mongoid
       #   DocumentNotFound.new(Person, :ssn => "1234", :name => "Helen")
       #
       # @param [ Class ] klass The model class.
-      # @param [ Hash, Array, Object ] params The attributes or ids.
-      # @param [ Array ] unmatched The unmatched ids, if appropriate
+      # @param [ Hash | Array | Object ] params The attributes or ids.
+      # @param [ Array | Hash ] unmatched The unmatched ids, if appropriate. If
+      #   there is a shard key this will be a hash.
       def initialize(klass, params, unmatched = nil)
         if !unmatched && !params.is_a?(Hash)
-          unmatched = Array(params)
+          unmatched = Array(params) if params
         end
 
         @klass, @params = klass, params
         super(
           compose_message(
-            message_key(params),
+            message_key(params, unmatched),
             {
               klass: klass.name,
               searched: searched(params),
               attributes: params,
               total: total(params),
-              missing: missing(unmatched)
+              missing: missing(unmatched),
+              shard_key: shard_key(unmatched)
             }
           )
         )
@@ -48,12 +50,14 @@ module Mongoid
       # @example Get the missing string.
       #   error.missing(1)
       #
-      # @param [ Object, Array ] unmatched The ids that did not match.
+      # @param [ Object | Array ] unmatched The ids that did not match.
       #
       # @return [ String ] The missing string.
       def missing(unmatched)
         if unmatched.is_a?(::Array)
           unmatched.join(", ")
+        elsif unmatched.is_a?(::Hash)
+          unmatched[:_id] || unmatched["_id"]
         else
           unmatched
         end
@@ -64,7 +68,7 @@ module Mongoid
       # @example Get the searched string.
       #   error.searched(1)
       #
-      # @param [ Object, Array ] params The ids that were searched for.
+      # @param [ Object | Array ] params The ids that were searched for.
       #
       # @return [ String ] The searched string.
       def searched(params)
@@ -80,7 +84,7 @@ module Mongoid
       # @example Get the total.
       #   error.total([ 1, 2, 3 ])
       #
-      # @param [ Object, Array ] params What was searched for.
+      # @param [ Object | Array ] params What was searched for.
       #
       # @return [ Integer ] The total number.
       def total(params)
@@ -93,10 +97,27 @@ module Mongoid
       #   error.problem
       #
       # @return [ String ] The problem.
-      def message_key(params)
-        case params
-          when Hash then "document_with_attributes_not_found"
-          else "document_not_found"
+      def message_key(params, unmatched)
+        if !params && !unmatched
+          "no_documents_found"
+        elsif Hash === params
+          "document_with_attributes_not_found"
+        elsif Hash === unmatched && unmatched.size >= 2
+          "document_with_shard_key_not_found"
+        else
+          "document_not_found"
+        end
+      end
+
+      # Get the shard key from the unmatched hash.
+      #
+      # @return [ String ] the shard key and value.
+      def shard_key(unmatched)
+        if Hash === unmatched
+          h = unmatched.dup
+          h.delete("_id")
+          h.delete(:_id)
+          h.map{|k,v| "#{k}: #{v}" }.join(", ")
         end
       end
     end