mongoid 6.4.4 → 7.5.1

data/lib/mongoid/criteria.rb

@@ -1,4 +1,5 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 require "mongoid/criteria/findable"
 require "mongoid/criteria/includable"
 require "mongoid/criteria/inspectable"
@@ -18,25 +19,31 @@ module Mongoid
   # against the database.
   class Criteria
     include Enumerable
+
+    # @api private
+    alias :_enumerable_find :find
+
     include Contextual
     include Queryable
     include Findable
+
+    # @api private
+    alias :_findable_find :find
+
     include Inspectable
     include Includable
     include Marshalable
     include Modifiable
     include Scopable
     include Clients::Options
-    include Options
     include Clients::Sessions
+    include Options
 
     # Static array used to check with method missing - we only need to ever
     # instantiate once.
-    #
-    # @since 4.0.0
     CHECK = []
 
-    attr_accessor :embedded, :klass, :parent_document, :metadata
+    attr_accessor :embedded, :klass, :parent_document, :association
 
     # Returns true if the supplied +Enumerable+ or +Criteria+ is equal to the results
     # of this +Criteria+ or the criteria itself.
@@ -46,13 +53,53 @@ module Mongoid
     # @param [ Object ] other The other +Enumerable+ or +Criteria+ to compare to.
     #
     # @return [ true, false ] If the objects are equal.
-    #
-    # @since 1.0.0
     def ==(other)
       return super if other.respond_to?(:selector)
       entries == other
     end
 
+    # Finds one or many documents given the provided _id values, or filters
+    # the documents in the current scope in the application process space
+    # after loading them if needed.
+    #
+    # If this method is not given a block, it delegates to +Findable#find+
+    # and finds one or many documents for the provided _id values.
+    #
+    # If this method is given a block, it delegates to +Enumerable#find+ and
+    # returns the first document of those found by the current Crieria object
+    # for which the block returns a truthy value.
+    #
+    # Note that the "default proc" argument of Enumerable is not specially
+    # treated by Mongoid - the decision between delegating to +Findable+ vs
+    # +Enumerable+ is made solely based on whether +find+ is passed a block.
+    #
+    # @example Finds a document by its _id, invokes Findable#find.
+    #   critera.find("1234")
+    #
+    # @example Finds the first matching document using a block, invokes Enumerable#find.
+    #   criteria.find { |item| item.name == "Depeche Mode" }
+    #
+    # @example Finds the first matching document using a block using the default Proc, invokes Enumerable#find.
+    #   criteria.find(-> { "Default Band" }) { |item| item.name == "Milwaukee Mode" }
+    #
+    # @example Tries to find a document whose _id is the stringification of the provided Proc, typically failing.
+    #   enumerator = criteria.find(-> { "Default Band" })
+    #
+    # @return [ Document | Array<Document> | nil ] A document or matching documents.
+    #
+    # @raise Errors::DocumentNotFound If the parameters were _id values and
+    #   not all documents are found and the +raise_not_found_error+
+    #   Mongoid configuration option is truthy.
+    #
+    # @see https://ruby-doc.org/core/Enumerable.html#method-i-find
+    def find(*args, &block)
+      if block_given?
+        _enumerable_find(*args, &block)
+      else
+        _findable_find(*args)
+      end
+    end
+
     # Needed to properly get a criteria back as json
     #
     # @example Get the criteria as json.
@@ -75,6 +122,7 @@ module Mongoid
     #
     # @return [ Criteria ] The cloned criteria.
     def cache
+      Mongoid::Warnings.warn_criteria_cache_deprecated
       crit = clone
       crit.options.merge!(cache: true)
       crit
@@ -87,6 +135,7 @@ module Mongoid
     #
     # @return [ true, false ] If the criteria is flagged as cached.
     def cached?
+      Mongoid::Warnings.warn_criteria_cache_deprecated
       options[:cache] == true
     end
 
@@ -96,8 +145,6 @@ module Mongoid
     #   criteria.documents
     #
     # @return [ Array<Document> ] The documents.
-    #
-    # @since 3.0.0
     def documents
       @documents ||= []
     end
@@ -109,8 +156,6 @@ module Mongoid
     # @param [ Array<Document> ] docs The embedded documents.
     #
     # @return [ Array<Document> ] The embedded documents.
-    #
-    # @since 3.0.0
     def documents=(docs)
       @documents = docs
     end
@@ -121,8 +166,6 @@ module Mongoid
     #   criteria.embedded?
     #
     # @return [ true, false ] If the criteria is embedded.
-    #
-    # @since 3.0.0
     def embedded?
       !!@embedded
     end
@@ -134,8 +177,6 @@ module Mongoid
     #   criteria.extract_id
     #
     # @return [ Object ] The id.
-    #
-    # @since 2.3.0
     def extract_id
       selector.extract_id
     end
@@ -149,8 +190,6 @@ module Mongoid
     # @param [ Hash ] extras The extra driver options.
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 2.0.0
     def extras(extras)
       crit = clone
       crit.options.merge!(extras)
@@ -163,11 +202,9 @@ module Mongoid
     #   criteria.field_list
     #
     # @return [ Array<String> ] The fields.
-    #
-    # @since 2.0.0
     def field_list
       if options[:fields]
-        options[:fields].keys.reject{ |key| key == "_type" }
+        options[:fields].keys.reject{ |key| key == klass.discriminator_key }
       else
         []
       end
@@ -181,8 +218,6 @@ module Mongoid
     #   criteria.freeze
     #
     # @return [ Criteria ] The frozen criteria.
-    #
-    # @since 2.0.0
     def freeze
       context and inclusions and super
     end
@@ -193,8 +228,6 @@ module Mongoid
     #   Criteria.new(Band)
     #
     # @param [ Class ] klass The model class.
-    #
-    # @since 1.0.0
     def initialize(klass)
       @klass = klass
       @embedded = nil
@@ -236,8 +269,6 @@ module Mongoid
     # @param [ Criteria ] other The criteria to merge in.
     #
     # @return [ Criteria ] The merged criteria.
-    #
-    # @since 3.0.0
     def merge!(other)
       criteria = other.to_criteria
       selector.merge!(criteria.selector)
@@ -255,8 +286,6 @@ module Mongoid
     #   criteria.none
     #
     # @return [ Criteria ] The none criteria.
-    #
-    # @since 4.0.0
     def none
       @none = true and self
     end
@@ -267,8 +296,6 @@ module Mongoid
     #   criteria.empty_and_chainable?
     #
     # @return [ true, false ] If the criteria is a none.
-    #
-    # @since 4.0.0
     def empty_and_chainable?
       !!@none
     end
@@ -281,19 +308,16 @@ module Mongoid
     # @param [ Array<Symbol> ] args The names of the fields.
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 1.0.0
     def only(*args)
-      return clone if args.flatten.empty?
       args = args.flatten
+      return clone if args.empty?
       if (args & Fields::IDS).empty?
         args.unshift(:_id)
       end
       if klass.hereditary?
-        super(*args.push(:_type))
-      else
-        super(*args)
+        args.push(klass.discriminator_key.to_sym)
       end
+      super(*args)
     end
 
     # Set the read preference for the criteria.
@@ -304,8 +328,6 @@ module Mongoid
     # @param [ Hash ] value The mode preference.
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 5.0.0
     def read(value = nil)
       clone.tap do |criteria|
         criteria.options.merge!(read: value)
@@ -320,10 +342,8 @@ module Mongoid
     # @param [ Array<Symbol> ] args The names of the fields.
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 4.0.3
     def without(*args)
-      args -= Fields::IDS
+      args -= id_fields
       super(*args)
     end
 
@@ -348,8 +368,6 @@ module Mongoid
     #   criteria.to_criteria
     #
     # @return [ Criteria ] self.
-    #
-    # @since 3.0.0
     def to_criteria
       self
     end
@@ -360,8 +378,6 @@ module Mongoid
     #   criteria.to_proc
     #
     # @return [ Proc ] The wrapped criteria.
-    #
-    # @since 3.0.0
     def to_proc
       ->{ self }
     end
@@ -377,7 +393,7 @@ module Mongoid
     #
     # @return [ Criteria ] The cloned criteria.
     def type(types)
-      any_in(_type: Array(types))
+      any_in(self.discriminator_key.to_sym => Array(types))
     end
 
     # This is the general entry point for most MongoDB queries. This either
@@ -396,11 +412,22 @@ module Mongoid
     #   is embedded.
     #
     # @return [ Criteria ] The cloned selectable.
-    #
-    # @since 1.0.0
-    def where(expression)
-      if expression.is_a?(::String) && embedded?
-        raise Errors::UnsupportedJavascript.new(klass, expression)
+    def where(*args)
+      # Historically this method required exactly one argument.
+      # As of https://jira.mongodb.org/browse/MONGOID-4804 it also accepts
+      # zero arguments.
+      # The underlying where implemetation that super invokes supports
+      # any number of arguments, but we don't presently allow mutiple
+      # arguments through this method. This API can be reconsidered in the
+      # future.
+      if args.length > 1
+        raise ArgumentError, "Criteria#where requires zero or one arguments (given #{args.length})"
+      end
+      if args.length == 1
+        expression = args.first
+        if expression.is_a?(::String) && embedded?
+          raise Errors::UnsupportedJavascript.new(klass, expression)
+        end
       end
       super
     end
@@ -412,8 +439,6 @@ module Mongoid
     #   criteria.without_options
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 3.0.4
     def without_options
       crit = clone
       crit.options.clear
@@ -432,10 +457,14 @@ module Mongoid
     # @param [ Hash ] scope The scope for the code.
     #
     # @return [ Criteria ] The criteria.
-    #
-    # @since 3.1.0
     def for_js(javascript, scope = {})
-      js_query(BSON::CodeWithScope.new(javascript, scope))
+      code = if scope.empty?
+        # CodeWithScope is not supported for $where as of MongoDB 4.4
+        BSON::Code.new(javascript)
+      else
+        BSON::CodeWithScope.new(javascript, scope)
+      end
+      js_query(code)
     end
 
     private
@@ -453,8 +482,6 @@ module Mongoid
     #
     # @raise [ Errors::DocumentNotFound ] If none are found and raising an
     #   error.
-    #
-    # @since 3.0.0
     def check_for_missing_documents!(result, ids)
       if (result.size < ids.size) && Mongoid.raise_not_found_error
         raise Errors::DocumentNotFound.new(klass, ids, ids - result.map(&:_id))
@@ -475,8 +502,6 @@ module Mongoid
     # @param [ Criteria ] other The criteria getting cloned.
     #
     # @return [ nil ] nil.
-    #
-    # @since 1.0.0
     def initialize_copy(other)
       @inclusions = other.inclusions.dup
       @scoping_options = other.scoping_options
@@ -495,9 +520,7 @@ module Mongoid
     # @param [ Array ] args The arguments.
     #
     # @return [ Object ] The result of the method call.
-    #
-    # @since 1.0.0
-    def method_missing(name, *args, &block)
+    ruby2_keywords def method_missing(name, *args, &block)
       if klass.respond_to?(name)
         klass.send(:with_scope, self) do
           klass.send(name, *args, &block)
@@ -516,8 +539,6 @@ module Mongoid
     #   criteria.merge_type_selection
     #
     # @return [ true, false ] If type selection was added.
-    #
-    # @since 3.0.3
     def merge_type_selection
       selector.merge!(type_selection) if type_selectable?
     end
@@ -530,12 +551,10 @@ module Mongoid
     #   criteria.type_selectable?
     #
     # @return [ true, false ] If type selection should be added.
-    #
-    # @since 3.0.3
     def type_selectable?
       klass.hereditary? &&
-        !selector.keys.include?("_type") &&
-        !selector.keys.include?(:_type)
+        !selector.keys.include?(self.discriminator_key) &&
+        !selector.keys.include?(self.discriminator_key.to_sym)
     end
 
     # Get the selector for type selection.
@@ -546,14 +565,12 @@ module Mongoid
     #   criteria.type_selection
     #
     # @return [ Hash ] The type selection.
-    #
-    # @since 3.0.3
     def type_selection
       klasses = klass._types
       if klasses.size > 1
-        { _type: { "$in" => klass._types }}
+        { klass.discriminator_key.to_sym => { "$in" => klass._types }}
       else
-        { _type: klass._types[0] }
+        { klass.discriminator_key.to_sym => klass._types[0] }
       end
     end
 
@@ -565,8 +582,6 @@ module Mongoid
     #   criteria.selector_with_type_selection
     #
     # @return [ Hash ] The selector.
-    #
-    # @since 3.0.3
     def selector_with_type_selection
       type_selectable? ? selector.merge(type_selection) : selector
     end

data/lib/mongoid/document.rb

@@ -1,10 +1,10 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 require "mongoid/positional"
 require "mongoid/evolvable"
 require "mongoid/extensions"
 require "mongoid/errors"
 require "mongoid/threaded"
-require "mongoid/relations"
 require "mongoid/atomic"
 require "mongoid/attributes"
 require "mongoid/contextual"
@@ -14,7 +14,9 @@ require "mongoid/criteria"
 require "mongoid/factory"
 require "mongoid/fields"
 require "mongoid/timestamps"
+require "mongoid/association"
 require "mongoid/composable"
+require "mongoid/touchable"
 
 module Mongoid
 
@@ -23,6 +25,7 @@ module Mongoid
   module Document
     extend ActiveSupport::Concern
     include Composable
+    include Mongoid::Touchable::InstanceMethods
 
     attr_accessor :__selected_fields
     attr_reader :new_record
@@ -36,8 +39,6 @@ module Mongoid
     # that should be used instead.
     # When ruby driver 2.3.0 is released and Mongoid can be updated
     # to require >= 2.3.0, the BSON constant can be used.
-    #
-    # @since 6.0.0
     ILLEGAL_KEY = /(\A[$])|(\.)/.freeze
 
     # Freezes the internal attributes of the document.
@@ -46,8 +47,6 @@ module Mongoid
     #   document.freeze
     #
     # @return [ Document ] The document.
-    #
-    # @since 2.0.0
     def freeze
       as_attributes.freeze and self
     end
@@ -58,8 +57,6 @@ module Mongoid
     #   document.frozen?
     #
     # @return [ true, false ] True if frozen, else false.
-    #
-    # @since 2.0.0
     def frozen?
       attributes.frozen?
     end
@@ -74,8 +71,6 @@ module Mongoid
     #   document.hash
     #
     # @return [ Integer ] The hash of the document's identity.
-    #
-    # @since 1.0.0
     def hash
       identity.hash
     end
@@ -88,8 +83,6 @@ module Mongoid
     #   document.identity
     #
     # @return [ Array ] An array containing [document.class, document._id]
-    #
-    # @since 3.0.0
     def identity
       [ self.class, self._id ]
     end
@@ -107,8 +100,6 @@ module Mongoid
     # @param [ Hash ] attrs The attributes to set up the document with.
     #
     # @return [ Document ] A new document.
-    #
-    # @since 1.0.0
     def initialize(attrs = nil)
       @__parent = nil
       _building do
@@ -132,8 +123,6 @@ module Mongoid
     #   document.model_name
     #
     # @return [ String ] The model name.
-    #
-    # @since 3.0.16
     def model_name
       self.class.model_name
     end
@@ -144,10 +133,8 @@ module Mongoid
     #   document.to_key
     #
     # @return [ String ] The id of the document or nil if new.
-    #
-    # @since 2.4.0
     def to_key
-      (persisted? || destroyed?) ? [ id.to_s ] : nil
+      (persisted? || destroyed?) ? [ _id.to_s ] : nil
     end
 
     # Return an array with this +Document+ only in it.
@@ -157,7 +144,7 @@ module Mongoid
     #
     # @return [ Array<Document> ] An array with the document as its only item.
     #
-    # @since 1.0.0
+    # @deprecated
     def to_a
       [ self ]
     end
@@ -170,28 +157,32 @@ module Mongoid
     #   person.as_document
     #
     # @return [ Hash ] A hash of all attributes in the hierarchy.
-    #
-    # @since 1.0.0
     def as_document
       BSON::Document.new(as_attributes)
     end
 
     # Calls #as_json on the document with additional, Mongoid-specific options.
     #
+    # @note Rails 6 changes return value of as_json for non-primitive types
+    #   such as BSON::ObjectId. In Rails <= 5, as_json returned these as
+    #   instances of the class. In Rails 6, these are returned serialized to
+    #   primitive types (e.g. {"$oid"=>"5bcfc40bde340b37feda98e9"}).
+    #   See https://github.com/rails/rails/commit/2e5cb980a448e7f4ab00df6e9ad4c1cc456616aa
+    #   for more information.
+    #
     # @example Get the document as json.
     #   document.as_json(compact: true)
     #
     # @param [ Hash ] options The options.
     #
-    # @option options [ true, false ] :compact Whether to include fields with
-    #   nil values in the json document.
+    # @option options [ true, false ] :compact (Deprecated) Whether to include fields
+    #   with nil values in the json document.
     #
     # @return [ Hash ] The document as json.
-    #
-    # @since 5.1.0
     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.')
         rv = rv.compact
       end
       rv
@@ -208,8 +199,6 @@ module Mongoid
     # @param [ Class ] klass The class to become.
     #
     # @return [ Document ] An instance of the specified class.
-    #
-    # @since 2.0.0
     def becomes(klass)
       unless klass.include?(Mongoid::Document)
         raise ArgumentError, "A class which includes Mongoid::Document is expected"
@@ -218,12 +207,13 @@ module Mongoid
       became = klass.new(clone_document)
       became._id = _id
       became.instance_variable_set(:@changed_attributes, changed_attributes)
-      became.instance_variable_set(:@errors, ActiveModel::Errors.new(became))
-      became.errors.instance_variable_set(:@messages, errors.instance_variable_get(:@messages))
+      new_errors = ActiveModel::Errors.new(became)
+      new_errors.copy!(errors)
+      became.instance_variable_set(:@errors, new_errors)
       became.instance_variable_set(:@new_record, new_record?)
       became.instance_variable_set(:@destroyed, destroyed?)
-      became.changed_attributes["_type"] = self.class.to_s
-      became._type = klass.to_s
+      became.changed_attributes[klass.discriminator_key] = self.class.discriminator_value
+      became[klass.discriminator_key] = klass.discriminator_value
 
       # mark embedded docs as persisted
       embedded_relations.each_pair do |name, meta|
@@ -243,8 +233,6 @@ module Mongoid
     # Returns the logger
     #
     # @return [ Logger ] The configured logger or a default Logger instance.
-    #
-    # @since 2.2.0
     def logger
       Mongoid.logger
     end
@@ -255,33 +243,17 @@ module Mongoid
     #   model.model_key
     #
     # @return [ String ] The model key.
-    #
-    # @since 2.4.0
     def model_key
       @model_cache_key ||= self.class.model_name.cache_key
     end
 
-    # Implement this for calls to flatten on array.
-    #
-    # @example Get the document as an array.
-    #   document.to_ary
-    #
-    # @return [ nil ] Always nil.
-    #
-    # @since 2.1.0
-    def to_ary
-      nil
-    end
-
-    private
-
     def as_attributes
       return attributes if frozen?
       embedded_relations.each_pair do |name, meta|
         without_autobuild do
           relation, stored = send(name), meta.store_as
           if attributes.key?(stored) || !relation.blank?
-            if relation
+            if !relation.nil?
               attributes[stored] = relation.send(:as_attributes)
             else
               attributes.delete(stored)
@@ -294,20 +266,6 @@ module Mongoid
 
     module ClassMethods
 
-      # Performs class equality checking.
-      #
-      # @example Compare the classes.
-      #   document === other
-      #
-      # @param [ Document, Object ] other The other object to compare with.
-      #
-      # @return [ true, false ] True if the classes are equal, false if not.
-      #
-      # @since 2.0.0.rc.4
-      def ===(other)
-        other.class == Class ? self <= other : other.is_a?(self)
-      end
-
       # Instantiate a new object, only when loaded from the database or when
       # the attributes have already been typecast.
       #
@@ -319,8 +277,6 @@ module Mongoid
       #   criteria.
       #
       # @return [ Document ] A new document.
-      #
-      # @since 1.0.0
       def instantiate(attrs = nil, selected_fields = nil)
         attributes = attrs || {}
         doc = allocate
@@ -339,17 +295,25 @@ module Mongoid
       #   document._types
       #
       # @return [ Array<Class> ] All subclasses of the current document.
-      #
-      # @since 1.0.0
       def _types
-        @_type ||= (descendants + [ self ]).uniq.map(&:to_s)
+        @_type ||= (descendants + [ self ]).uniq.map(&:discriminator_value)
+      end
+
+      # Clear the @_type cache. This is generally called when changing the discriminator
+      # key/value on a class.
+      #
+      # @example Get the types.
+      #   document._mongoid_clear_types
+      #
+      # @api private
+      def _mongoid_clear_types
+        @_type = nil
+        superclass._mongoid_clear_types if hereditary?
       end
 
       # Set the i18n scope to overwrite ActiveModel.
       #
       # @return [ Symbol ] :mongoid
-      #
-      # @since 2.0.0
       def i18n_scope
         :mongoid
       end
@@ -360,8 +324,6 @@ module Mongoid
       #   Person.logger
       #
       # @return [ Logger ] The configured logger or a default Logger instance.
-      #
-      # @since 2.2.0
       def logger
         Mongoid.logger
       end