mongoid 7.2.1 → 9.0.0

data/lib/mongoid/criteria.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
-# encoding: utf-8
+# rubocop:todo all
 
 require "mongoid/criteria/findable"
 require "mongoid/criteria/includable"
@@ -9,6 +9,7 @@ require "mongoid/criteria/modifiable"
 require "mongoid/criteria/queryable"
 require "mongoid/criteria/scopable"
 require "mongoid/criteria/options"
+require "mongoid/criteria/translator"
 
 module Mongoid
 
@@ -40,10 +41,28 @@ module Mongoid
     include Clients::Sessions
     include Options
 
+    class << self
+      # Convert the given hash to a criteria. Will iterate over each keys in the
+      # hash which must correspond to method on a criteria object. The hash
+      # must also include a "klass" key.
+      #
+      # @example Convert the hash to a criteria.
+      #   Criteria.from_hash({ klass: Band, where: { name: "Depeche Mode" })
+      #
+      # @param [ Hash ] hash The hash to convert.
+      #
+      # @return [ Criteria ] The criteria.
+      def from_hash(hash)
+        criteria = Criteria.new(hash.delete(:klass) || hash.delete('klass'))
+        hash.each_pair do |method, args|
+          criteria = criteria.__send__(method, args)
+        end
+        criteria
+      end
+    end
+
     # 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, :association
@@ -55,9 +74,7 @@ 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
@@ -78,6 +95,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")
     #
@@ -90,6 +110,10 @@ 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 id(s).
+    # @param &block Optional block to pass.
+    # @yield [ Object ] Yields each enumerable element to the block.
+    #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
     #
     # @raise Errors::DocumentNotFound If the parameters were _id values and
@@ -117,39 +141,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
@@ -161,8 +158,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
@@ -172,9 +167,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
@@ -186,10 +179,8 @@ module Mongoid
     #   criteria.extract_id
     #
     # @return [ Object ] The id.
-    #
-    # @since 2.3.0
     def extract_id
-      selector.extract_id
+      selector['_id'] || selector[:_id] || selector['id'] || selector[:id]
     end
 
     # Adds a criterion to the +Criteria+ that specifies additional options
@@ -201,8 +192,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)
@@ -215,8 +204,6 @@ 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 == klass.discriminator_key }
@@ -233,8 +220,6 @@ module Mongoid
     #   criteria.freeze
     #
     # @return [ Criteria ] The frozen criteria.
-    #
-    # @since 2.0.0
     def freeze
       context and inclusions and super
     end
@@ -245,13 +230,11 @@ module Mongoid
     #   Criteria.new(Band)
     #
     # @param [ Class ] klass The model class.
-    #
-    # @since 1.0.0
     def initialize(klass)
       @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.
@@ -260,7 +243,7 @@ module Mongoid
     # may be desired.
     #
     # @example Merge the criteria with another criteria.
-    #   criteri.merge(other_criteria)
+    #   criteria.merge(other_criteria)
     #
     # @example Merge the criteria with a hash. The hash must contain a klass
     #   key and the key/value pairs correspond to method names/args.
@@ -285,18 +268,16 @@ module Mongoid
     # @example Merge another criteria into this criteria.
     #   criteria.merge(Person.where(name: "bob"))
     #
-    # @param [ Criteria ] other The criteria to merge in.
+    # @param [ Criteria | Hash ] 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).uniq
+      other = self.class.from_hash(other) if other.is_a?(Hash)
+      selector.merge!(other.selector)
+      options.merge!(other.options)
+      self.documents = other.documents.dup unless other.documents.empty?
+      self.scoping_options = other.scoping_options
+      self.inclusions = (inclusions + other.inclusions).uniq
       self
     end
 
@@ -307,8 +288,6 @@ module Mongoid
     #   criteria.none
     #
     # @return [ Criteria ] The none criteria.
-    #
-    # @since 4.0.0
     def none
       @none = true and self
     end
@@ -318,9 +297,7 @@ module Mongoid
     # @example Is the criteria a none criteria?
     #   criteria.empty_and_chainable?
     #
-    # @return [ true, false ] If the criteria is a none.
-    #
-    # @since 4.0.0
+    # @return [ true | false ] If the criteria is a none.
     def empty_and_chainable?
       !!@none
     end
@@ -330,22 +307,19 @@ module Mongoid
     # @example Limit the fields returned from the database.
     #   Band.only(:name)
     #
-    # @param [ Array<Symbol> ] args The names of the fields.
+    # @param [ [ Symbol | Array<Symbol> ]... ] *args The field name(s).
     #
     # @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(klass.discriminator_key.to_sym))
-      else
-        super(*args)
+        args.push(klass.discriminator_key.to_sym)
       end
+      super(*args)
     end
 
     # Set the read preference for the criteria.
@@ -356,8 +330,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)
@@ -369,13 +341,11 @@ module Mongoid
     # @example Exclude fields returned from the database.
     #   Band.without(:name)
     #
-    # @param [ Array<Symbol> ] args The names of the fields.
+    # @param [ Symbol... ] *args The field name(s).
     #
     # @return [ Criteria ] The cloned criteria.
-    #
-    # @since 4.0.3
     def without(*args)
-      args -= Fields::IDS
+      args -= id_fields
       super(*args)
     end
 
@@ -385,9 +355,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
@@ -400,11 +370,11 @@ module Mongoid
     #   criteria.to_criteria
     #
     # @return [ Criteria ] self.
-    #
-    # @since 3.0.0
+    # @deprecated
     def to_criteria
       self
     end
+    Mongoid.deprecate(self, :to_criteria)
 
     # Convert the criteria to a proc.
     #
@@ -412,8 +382,6 @@ module Mongoid
     #   criteria.to_proc
     #
     # @return [ Proc ] The wrapped criteria.
-    #
-    # @since 3.0.0
     def to_proc
       ->{ self }
     end
@@ -442,14 +410,13 @@ module Mongoid
     # @example Add a javascript selection.
     #   criteria.where("this.name == 'syd'")
     #
-    # @param [ String, Hash ] expression The javascript or standard selection.
+    # @param [ [ Hash | String ]... ] *args The standard selection
+    #   or javascript string.
     #
     # @raise [ UnsupportedJavascript ] If provided a string and the criteria
     #   is embedded.
     #
     # @return [ Criteria ] The cloned selectable.
-    #
-    # @since 1.0.0
     def where(*args)
       # Historically this method required exactly one argument.
       # As of https://jira.mongodb.org/browse/MONGOID-4804 it also accepts
@@ -470,15 +437,12 @@ module Mongoid
       super
     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
@@ -498,7 +462,7 @@ module Mongoid
     #
     # @return [ Criteria ] The criteria.
     #
-    # @since 3.1.0
+    # @deprecated
     def for_js(javascript, scope = {})
       code = if scope.empty?
         # CodeWithScope is not supported for $where as of MongoDB 4.4
@@ -508,6 +472,7 @@ module Mongoid
       end
       js_query(code)
     end
+    Mongoid.deprecate(self, :for_js)
 
     private
 
@@ -524,8 +489,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))
@@ -546,8 +509,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
@@ -563,12 +524,10 @@ module Mongoid
     #   criteria.method_missing(:name)
     #
     # @param [ Symbol ] name The method name.
-    # @param [ Array ] args The arguments.
+    # @param [ Object... ] *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)
@@ -586,9 +545,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
@@ -600,9 +557,7 @@ 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?(self.discriminator_key) &&
@@ -617,8 +572,6 @@ module Mongoid
     #   criteria.type_selection
     #
     # @return [ Hash ] The type selection.
-    #
-    # @since 3.0.3
     def type_selection
       klasses = klass._types
       if klasses.size > 1
@@ -636,8 +589,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,38 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+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,29 @@
+# frozen_string_literal: true
+# rubocop:todo all
+
+module Mongoid
+
+  # Utility class for logging deprecation warnings.
+  class Deprecation < ::ActiveSupport::Deprecation
+
+    def initialize
+      # Per change policy, deprecations will be removed in the next major version.
+      deprecation_horizon = "#{Mongoid::VERSION.split('.').first.to_i + 1}.0".freeze
+      gem_name = 'Mongoid'
+      super(deprecation_horizon, gem_name)
+    end
+
+
+    # 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