mongoid 3.1.5 → 8.0.2

data/lib/mongoid/criteria.rb

@@ -1,9 +1,13 @@
-# encoding: utf-8
-require "mongoid/criterion/inspection"
-require "mongoid/criterion/findable"
-require "mongoid/criterion/marshalable"
-require "mongoid/criterion/modifiable"
-require "mongoid/criterion/scoping"
+# frozen_string_literal: true
+
+require "mongoid/criteria/findable"
+require "mongoid/criteria/includable"
+require "mongoid/criteria/inspectable"
+require "mongoid/criteria/marshalable"
+require "mongoid/criteria/modifiable"
+require "mongoid/criteria/queryable"
+require "mongoid/criteria/scopable"
+require "mongoid/criteria/options"
 
 module Mongoid
 
@@ -15,21 +19,31 @@ module Mongoid
   # against the database.
   class Criteria
     include Enumerable
+
+    # @api private
+    alias :_enumerable_find :find
+
     include Contextual
-    include Origin::Queryable
-    include Criterion::Inspection
-    include Criterion::Findable
-    include Criterion::Marshalable
-    include Criterion::Modifiable
-    include Criterion::Scoping
+    include Queryable
+    include Findable
+
+    # @api private
+    alias :_findable_find :find
+
+    include Inspectable
+    include Includable
+    include Marshalable
+    include Modifiable
+    include Scopable
+    include Clients::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
+    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.
@@ -38,14 +52,60 @@ 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
+    # @return [ true | false ] If the objects are equal.
     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.
+    #
+    # @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")
+    #
+    # @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" })
+    #
+    # @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
+    #   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.
@@ -58,39 +118,12 @@ 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.
     #   criteria.documents
     #
     # @return [ Array<Document> ] The documents.
-    #
-    # @since 3.0.0
     def documents
       @documents ||= []
     end
@@ -102,8 +135,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
@@ -113,9 +144,7 @@ module Mongoid
     # @example Is the criteria for embedded documents?
     #   criteria.embedded?
     #
-    # @return [ true, false ] If the criteria is embedded.
-    #
-    # @since 3.0.0
+    # @return [ true | false ] If the criteria is embedded.
     def embedded?
       !!@embedded
     end
@@ -127,8 +156,6 @@ module Mongoid
     #   criteria.extract_id
     #
     # @return [ Object ] The id.
-    #
-    # @since 2.3.0
     def extract_id
       selector.extract_id
     end
@@ -142,8 +169,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)
@@ -156,11 +181,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
@@ -174,8 +197,6 @@ module Mongoid
     #   criteria.freeze
     #
     # @return [ Criteria ] The frozen criteria.
-    #
-    # @since 2.0.0
     def freeze
       context and inclusions and super
     end
@@ -186,70 +207,11 @@ module Mongoid
     #   Criteria.new(Band)
     #
     # @param [ Class ] klass The model class.
-    #
-    # @since 1.0.0
     def initialize(klass)
       @klass = klass
-      klass ? super(klass.aliased_fields, klass.fields) : super({}, {})
-    end
-
-    # Eager loads all the provided relations. Will load all the documents
-    # into the identity map who's ids match based on the extra query for the
-    # ids.
-    #
-    # @note This will only work if Mongoid's identity map is enabled. To do
-    #   so set identity_map_enabled: true in your mongoid.yml
-    #
-    # @note This will work for embedded relations that reference another
-    #   collection via belongs_to as well.
-    #
-    # @note Eager loading brings all the documents into memory, so there is a
-    #   sweet spot on the performance gains. Internal benchmarks show that
-    #   eager loading becomes slower around 100k documents, but this will
-    #   naturally depend on the specific application.
-    #
-    # @example Eager load the provided relations.
-    #   Person.includes(:posts, :game)
-    #
-    # @param [ Array<Symbol> ] relations The names of the relations to eager
-    #   load.
-    #
-    # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 2.2.0
-    def includes(*relations)
-      relations.flatten.each do |name|
-        metadata = klass.reflect_on_association(name)
-        raise Errors::InvalidIncludes.new(klass, relations) unless metadata
-        inclusions.push(metadata) unless inclusions.include?(metadata)
-      end
-      clone
-    end
-
-    # Get a list of criteria that are to be executed for eager loading.
-    #
-    # @example Get the eager loading inclusions.
-    #   Person.includes(:game).inclusions
-    #
-    # @return [ Array<Metadata> ] The inclusions.
-    #
-    # @since 2.2.0
-    def inclusions
-      @inclusions ||= []
-    end
-
-    # Set the inclusions for the criteria.
-    #
-    # @example Set the inclusions.
-    #   criteria.inclusions = [ meta ]
-    #
-    # @param [ Array<Metadata> ] The inclusions.
-    #
-    # @return [ Array<Metadata> ] The new inclusions.
-    #
-    # @since 3.0.0
-    def inclusions=(value)
-      @inclusions = value
+      @embedded = nil
+      @none = nil
+      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.
@@ -262,7 +224,7 @@ module Mongoid
     #
     # @example Merge the criteria with a hash. The hash must contain a klass
     #   key and the key/value pairs correspond to method names/args.
-
+    #
     #   criteria.merge({
     #     klass: Band,
     #     where: { name: "Depeche Mode" },
@@ -286,18 +248,37 @@ 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)
       options.merge!(criteria.options)
       self.documents = criteria.documents.dup unless criteria.documents.empty?
       self.scoping_options = criteria.scoping_options
-      self.inclusions = (inclusions + criteria.inclusions.dup).uniq
+      self.inclusions = (inclusions + criteria.inclusions).uniq
       self
     end
 
+    # Returns a criteria that will always contain zero results and never hits
+    # the database.
+    #
+    # @example Return a none criteria.
+    #   criteria.none
+    #
+    # @return [ Criteria ] The none criteria.
+    def none
+      @none = true and self
+    end
+
+    # Is the criteria an empty but chainable criteria?
+    #
+    # @example Is the criteria a none criteria?
+    #   criteria.empty_and_chainable?
+    #
+    # @return [ true | false ] If the criteria is a none.
+    def empty_and_chainable?
+      !!@none
+    end
+
     # Overriden to include _type in the fields.
     #
     # @example Limit the fields returned from the database.
@@ -306,16 +287,43 @@ 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.
+    #
+    # @example Set the read preference.
+    #   criteria.read(mode: :primary_preferred)
+    #
+    # @param [ Hash ] value The mode preference.
+    #
+    # @return [ Criteria ] The cloned criteria.
+    def read(value = nil)
+      clone.tap do |criteria|
+        criteria.options.merge!(read: value)
+      end
+    end
+
+    # Overriden to exclude _id from the fields.
+    #
+    # @example Exclude fields returned from the database.
+    #   Band.without(:name)
+    #
+    # @param [ Array<Symbol> ] args The names of the fields.
+    #
+    # @return [ Criteria ] The cloned criteria.
+    def without(*args)
+      args -= id_fields
+      super(*args)
     end
 
     # Returns true if criteria responds to the given method.
@@ -324,9 +332,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
@@ -339,8 +347,6 @@ module Mongoid
     #   criteria.to_criteria
     #
     # @return [ Criteria ] self.
-    #
-    # @since 3.0.0
     def to_criteria
       self
     end
@@ -351,8 +357,6 @@ module Mongoid
     #   criteria.to_proc
     #
     # @return [ Proc ] The wrapped criteria.
-    #
-    # @since 3.0.0
     def to_proc
       ->{ self }
     end
@@ -368,7 +372,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
@@ -381,49 +385,38 @@ module Mongoid
     # @example Add a javascript selection.
     #   criteria.where("this.name == 'syd'")
     #
-    # @param [ String, Hash ] criterion 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.
     #
     # @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
 
-    # Tell the next persistance operation to query from a specific collection,
-    # database or session.
-    #
-    # @example Send the criteria to another collection.
-    #   Band.where(name: "Depeche Mode").with(collection: "artists")
-    #
-    # @param [ Hash ] options The storage options.
-    #
-    # @option options [ String, Symbol ] :collection The collection name.
-    # @option options [ String, Symbol ] :database The database name.
-    # @option options [ String, Symbol ] :session The session name.
-    #
-    # @return [ Criteria ] The criteria.
-    #
-    # @since 3.0.0
-    def with(options)
-      Threaded.set_persistence_options(klass, options)
-      self
-    end
-
     # Get a version of this criteria without the options.
     #
     # @example Get the criteria without options.
     #   criteria.without_options
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 3.0.4
     def without_options
       crit = clone
       crit.options.clear
@@ -442,10 +435,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(Moped::BSON::Code.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
@@ -463,8 +460,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))
@@ -485,8 +480,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
@@ -505,9 +498,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)
@@ -525,9 +516,7 @@ module Mongoid
     # @example Add the type selection.
     #   criteria.merge_type_selection
     #
-    # @return [ true, false ] If type selection was added.
-    #
-    # @since 3.0.3
+    # @return [ true | false ] If type selection was added.
     def merge_type_selection
       selector.merge!(type_selection) if type_selectable?
     end
@@ -539,13 +528,11 @@ module Mongoid
     # @example If the criteria type selectable?
     #   criteria.type_selectable?
     #
-    # @return [ true, false ] If type selection should be added.
-    #
-    # @since 3.0.3
+    # @return [ true | false ] If type selection should be added.
     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.
@@ -556,10 +543,13 @@ module Mongoid
     #   criteria.type_selection
     #
     # @return [ Hash ] The type selection.
-    #
-    # @since 3.0.3
     def type_selection
-      { _type: { "$in" => klass._types }}
+      klasses = klass._types
+      if klasses.size > 1
+        { klass.discriminator_key.to_sym => { "$in" => klass._types }}
+      else
+        { klass.discriminator_key.to_sym => klass._types[0] }
+      end
     end
 
     # Get a new selector with type selection in it.
@@ -570,8 +560,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/deprecable.rb

@@ -0,0 +1,36 @@
+# 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)
+      Mongoid::Deprecation.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(->(message, callstack, _deprecation_horizon, _gem_name) {
+        logger = Mongoid.logger
+        logger.warn(message)
+        logger.debug(callstack.join("\n  ")) if debug
+      })
+    end
+  end
+end