mongoid 7.0.6 → 7.1.2

data/lib/mongoid/criteria/queryable/macroable.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   class Criteria
     module Queryable
 
-      # Adds macro behaviour for adding symbol methods.
+      # Adds macro behavior for adding symbol methods.
       module Macroable
 
         # Adds a method on Symbol for convenience in where queries for the

data/lib/mongoid/criteria/queryable/mergeable.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   class Criteria
     module Queryable
 
-      # Contains behaviour for merging existing selection with new selection.
+      # Contains behavior for merging existing selection with new selection.
       module Mergeable
 
         # @attribute [rw] strategy The name of the current strategy.
@@ -50,12 +52,13 @@ module Mongoid
         # @example Reset the strategies.
         #   mergeable.reset_strategies!
         #
-        # @return [ nil ] nil.
+        # @return [ Criteria ] self.
         #
         # @since 1.0.0
         def reset_strategies!
           self.strategy = nil
           self.negating = nil
+          self
         end
 
         private
@@ -133,34 +136,170 @@ module Mongoid
           with_strategy(:__intersect__, criterion, operator)
         end
 
-        # Adds the criterion to the existing selection.
+        # Adds $and/$or/$nor criteria to a copy of this selection.
+        #
+        # Each of the criteria can be a Hash of key/value pairs or MongoDB
+        # operators (keys beginning with $), or a Selectable object
+        # (which typically will be a Criteria instance).
         #
         # @api private
         #
         # @example Add the criterion.
         #   mergeable.__multi__([ 1, 2 ], "$in")
         #
-        # @param [ Hash ] criterion The criteria.
+        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
+        #   matches or Criteria objects.
         # @param [ String ] operator The MongoDB operator.
         #
         # @return [ Mergeable ] The new mergeable.
         #
         # @since 1.0.0
-        def __multi__(criterion, operator)
+        def __multi__(criteria, operator)
           clone.tap do |query|
             sel = query.selector
-            criterion.flatten.each do |expr|
+            criteria.flatten.each do |expr|
               next unless expr
-              criteria = sel[operator] || []
-              normalized = expr.inject({}) do |hash, (field, value)|
-                hash.merge!(field.__expr_part__(value.__expand_complex__))
-                hash
+              result_criteria = sel[operator] || []
+              if expr.is_a?(Selectable)
+                expr = expr.selector
               end
-              sel.store(operator, criteria.push(normalized))
+              normalized = _mongoid_expand_keys(expr)
+              sel.store(operator, result_criteria.push(normalized))
             end
           end
         end
 
+        # Combines criteria into a MongoDB selector.
+        #
+        # Criteria is an array of criterions which will be flattened.
+        #
+        # Each criterion can be:
+        # - A hash
+        # - A Criteria instance
+        # - nil, in which case it is ignored
+        #
+        # @api private
+        private def _mongoid_add_top_level_operation(operator, criteria)
+          # Flatten the criteria. The idea is that predicates in MongoDB
+          # are always hashes and are never arrays. This method additionally
+          # allows Criteria instances as predicates.
+          # The flattening is existing Mongoid behavior but we could possibly
+          # get rid of it as applications can splat their predicates, or
+          # flatten if needed.
+          clone.tap do |query|
+            sel = query.selector
+            _mongoid_flatten_arrays(criteria).each do |criterion|
+              if criterion.is_a?(Selectable)
+                expr = _mongoid_expand_keys(criterion.selector)
+              else
+                expr = _mongoid_expand_keys(criterion)
+              end
+              if sel.empty?
+                sel.store(operator, [expr])
+              elsif sel.keys == [operator]
+                sel.store(operator, sel[operator] + [expr])
+              else
+                operands = [sel.dup] + [expr]
+                sel.clear
+                sel.store(operator, operands)
+              end
+            end
+          end
+        end
+
+        # Calling .flatten on an array which includes a Criteria instance
+        # evaluates the criteria, which we do not want. Hence this method
+        # explicitly only expands Array objects and Array subclasses.
+        private def _mongoid_flatten_arrays(array)
+          out = []
+          pending = array.dup
+          until pending.empty?
+            item = pending.shift
+            if item.nil?
+              # skip
+            elsif item.is_a?(Array)
+              pending += item
+            else
+              out << item
+            end
+          end
+          out
+        end
+
+        # Takes a criteria hash and expands Key objects into hashes containing
+        # MQL corresponding to said key objects.
+        #
+        # Ruby does not permit multiple symbol operators. For example,
+        # {:foo.gt => 1, :foo.gt => 2} is collapsed to {:foo.gt => 2} by the
+        # language. Therefore this method never has to deal with multiple
+        # identical operators.
+        #
+        # Similarly, this method should never need to expand a literal value
+        # and an operator at the same time.
+        #
+        # @param [ Hash ] Criteria including Key instances.
+        #
+        # @return [ Hash ] Expanded criteria.
+        private def _mongoid_expand_keys(expr)
+          unless expr.is_a?(Hash)
+            raise ArgumentError, 'Argument must be a Hash'
+          end
+
+          result = {}
+          expr.each do |field, value|
+            field.__expr_part__(value.__expand_complex__).each do |k, v|
+              if result[k]
+                if result[k].is_a?(Hash)
+                  # Existing value is an operator.
+                  # If new value is also an operator, ensure there are no
+                  # conflicts and add
+                  if v.is_a?(Hash)
+                    # The new value is also an operator.
+                    # If there are no conflicts, combine the hashes, otherwise
+                    # add new conditions to top level with $and.
+                    if (v.keys & result[k].keys).empty?
+                      result[k].update(v)
+                    else
+                      raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                      result['$and'] ||= []
+                      result['$and'] << {k => v}
+                    end
+                  else
+                    # The new value is a simple value.
+                    # If there isn't an $eq operator already in the query,
+                    # transform the new value into an $eq operator and add it
+                    # to the existing hash. Otherwise add the new condition
+                    # with $and to the top level.
+                    if result[k].key?('$eq')
+                      raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                      result['$and'] ||= []
+                      result['$and'] << {k => v}
+                    else
+                      result[k].update('$eq' => v)
+                    end
+                  end
+                else
+                  # Existing value is a simple value.
+                  # If we are adding an operator, and the operator is not $eq,
+                  # convert existing value into $eq and add the new operator
+                  # to the same hash. Otherwise add the new condition with $and
+                  # to the top level.
+                  if v.is_a?(Hash) && !v.key?('$eq')
+                    result[k] = {'$eq' => result[k]}.update(v)
+                  else
+                    raise NotImplementedError, 'Ruby does not allow same symbol operator with different values'
+                    result['$and'] ||= []
+                    result['$and'] << {k => v}
+                  end
+                end
+              else
+                result[k] = v
+              end
+            end
+          end
+          result
+        end
+
         # Adds the criterion to the existing selection.
         #
         # @api private
@@ -175,6 +314,9 @@ module Mongoid
         #
         # @since 1.0.0
         def __override__(criterion, operator)
+          if criterion.is_a?(Selectable)
+            criterion = criterion.selector
+          end
           selection(criterion) do |selector, field, value|
             expression = prepare(field, operator, value)
             existing = selector[field]

data/lib/mongoid/criteria/queryable/optional.rb

@@ -1,9 +1,11 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   class Criteria
     module Queryable
 
-      # The optional module includes all behaviour that has to do with extra
+      # The optional module includes all behavior that has to do with extra
       # options surrounding queries, like skip, limit, sorting, etc.
       module Optional
         extend Macroable
@@ -169,10 +171,10 @@ module Mongoid
         #   optional.order_by([[ name, 1 ], [ dob, -1 ]])
         #
         # @example Add sorting options via an array with symbol directions.
-        #   optional.order_by([[ name, :asc ], [ dob, :desc ]])
+        #   optional.order_by([[ :name, :asc ], [ :dob, :desc ]])
         #
         # @example Add sorting options via an array with string directions.
-        #   optional.order_by([[ name, "asc" ], [ dob, "desc" ]])
+        #   optional.order_by([[ "name", "asc" ], [ "dob", "desc" ]])
         #
         # @example Add sorting options with keys.
         #   optional.order_by(:name.asc, :dob.desc)

data/lib/mongoid/criteria/queryable/options.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   class Criteria
     module Queryable

data/lib/mongoid/criteria/queryable/pipeline.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   class Criteria
     module Queryable
@@ -31,7 +33,7 @@ module Mongoid
         # Add a group operation to the aggregation pipeline.
         #
         # @example Add a group operation.
-        #   pipeline.group(:count.sum => 1, :max.max => "likes")
+        #   pipeline.group(:_id => "foo", :count.sum => 1, :max.max => "likes")
         #
         # @param [ Hash ] entry The group entry.
         #
@@ -74,7 +76,8 @@ module Mongoid
         #   pipeline.unwind(:field)
         #   pipeline.unwind(document)
         #
-        # @param [ String, Symbol, Hash ] field_or_doc The name of the field or a document.
+        # @param [ String, Symbol, Hash ] field_or_doc A field name or a
+        #   document.
         #
         # @return [ Pipeline ] The pipeline.
         #

data/lib/mongoid/criteria/queryable/selectable.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
 # encoding: utf-8
+
 module Mongoid
   class Criteria
     module Queryable
@@ -41,8 +43,32 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def all(criterion = nil)
-          send(strategy || :__union__, with_array_values(criterion), "$all")
+        def all(*criteria)
+          if criteria.empty?
+            return clone.tap do |query|
+              query.reset_strategies!
+            end
+          end
+
+          criteria.inject(clone) do |query, condition|
+            if condition.nil?
+              raise Errors::CriteriaArgumentRequired, :all
+            end
+
+            condition = expand_condition_to_array_values(condition)
+
+            if strategy
+              send(strategy, condition, "$all")
+            else
+              condition.inject(query) do |_query, (field, value)|
+                v = {'$all' => value}
+                if negating?
+                  v = {'$not' => v}
+                end
+                _query.add_field_expression(field.to_s, v)
+              end
+            end
+          end.reset_strategies!
         end
         alias :all_in :all
         key :all, :union, "$all"
@@ -52,14 +78,44 @@ module Mongoid
         # @example Add the criterion.
         #   selectable.and({ field: value }, { other: value })
         #
-        # @param [ Array<Hash> ] criterion Multiple key/value pair matches that
-        #   all must match to return results.
+        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
+        #   matches or Criteria objects that all must match to return results.
         #
-        # @return [ Selectable ] The cloned selectable.
+        # @return [ Selectable ] The new selectable.
         #
         # @since 1.0.0
-        def and(*criterion)
-          __multi__(criterion, "$and")
+        def and(*criteria)
+          _mongoid_flatten_arrays(criteria).inject(self.clone) do |c, new_s|
+            if new_s.is_a?(Selectable)
+              new_s = new_s.selector
+            end
+            normalized = _mongoid_expand_keys(new_s)
+            normalized.each do |k, v|
+              k = k.to_s
+              if c.selector[k]
+                # There is already a condition on k.
+                # If v is an operator, and all existing conditions are
+                # also operators, and v isn't present in existing conditions,
+                # we can add to existing conditions.
+                # Otherwise use $and.
+                if v.is_a?(Hash) &&
+                  v.length == 1 &&
+                  (new_k = v.keys.first).start_with?('$') &&
+                  (existing_kv = c.selector[k]).is_a?(Hash) &&
+                  !existing_kv.key?(new_k) &&
+                  existing_kv.keys.all? { |sub_k| sub_k.start_with?('$') }
+                then
+                  merged_v = c.selector[k].merge(v)
+                  c.selector.store(k, merged_v)
+                else
+                  c = c.send(:__multi__, [k => v], '$and')
+                end
+              else
+                c.selector.store(k, v)
+              end
+            end
+            c
+          end
         end
         alias :all_of :and
 
@@ -76,7 +132,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def between(criterion = nil)
+        def between(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :between
+          end
+
           selection(criterion) do |selector, field, value|
             selector.store(
               field,
@@ -104,7 +164,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def elem_match(criterion = nil)
+        def elem_match(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :elem_match
+          end
+
           __override__(criterion, "$elemMatch")
         end
         key :elem_match, :override, "$elemMatch"
@@ -125,7 +189,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def exists(criterion = nil)
+        def exists(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :exists
+          end
+
           typed_override(criterion, "$exists") do |value|
             ::Boolean.evolve(value)
           end
@@ -170,7 +238,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 2.0.0
-        def geo_spacial(criterion = nil)
+        def geo_spacial(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :geo_spacial
+          end
+
           __merge__(criterion)
         end
         key :intersects_line, :override, "$geoIntersects", "$geometry" do |value|
@@ -200,7 +272,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def gt(criterion = nil)
+        def gt(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :gt
+          end
+
           __override__(criterion, "$gt")
         end
         key :gt, :override, "$gt"
@@ -218,7 +294,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def gte(criterion = nil)
+        def gte(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :gte
+          end
+
           __override__(criterion, "$gte")
         end
         key :gte, :override, "$gte"
@@ -234,13 +314,29 @@ module Mongoid
         # @example Execute an $in in a where query.
         #   selectable.where(:field.in => [ 1, 2, 3 ])
         #
-        # @param [ Hash ] criterion The field/value criterion pairs.
+        # @param [ Hash ] condition The field/value criterion pairs.
         #
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def in(criterion = nil)
-          send(strategy || :__intersect__, with_array_values(criterion), "$in")
+        def in(condition)
+          if condition.nil?
+            raise Errors::CriteriaArgumentRequired, :in
+          end
+
+          condition = expand_condition_to_array_values(condition)
+
+          if strategy
+            send(strategy, condition, "$in")
+          else
+            condition.inject(clone) do |query, (field, value)|
+              v = {'$in' => value}
+              if negating?
+                v = {'$not' => v}
+              end
+              query.add_field_expression(field.to_s, v)
+            end.reset_strategies!
+          end
         end
         alias :any_in :in
         key :in, :intersect, "$in"
@@ -258,7 +354,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def lt(criterion = nil)
+        def lt(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :lt
+          end
+
           __override__(criterion, "$lt")
         end
         key :lt, :override, "$lt"
@@ -276,7 +376,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def lte(criterion = nil)
+        def lte(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :lte
+          end
+
           __override__(criterion, "$lte")
         end
         key :lte, :override, "$lte"
@@ -291,7 +395,12 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def max_distance(criterion = nil)
+        def max_distance(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :max_distance
+          end
+
+          # $maxDistance must be given together with $near
           __add__(criterion, "$maxDistance")
         end
 
@@ -308,7 +417,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def mod(criterion = nil)
+        def mod(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :mod
+          end
+
           __override__(criterion, "$mod")
         end
         key :mod, :override, "$mod"
@@ -326,7 +439,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def ne(criterion = nil)
+        def ne(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :ne
+          end
+
           __override__(criterion, "$ne")
         end
         alias :excludes :ne
@@ -345,7 +462,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def near(criterion = nil)
+        def near(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :near
+          end
+
           __override__(criterion, "$near")
         end
         key :near, :override, "$near"
@@ -363,7 +484,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def near_sphere(criterion = nil)
+        def near_sphere(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :near_sphere
+          end
+
           __override__(criterion, "$nearSphere")
         end
         key :near_sphere, :override, "$nearSphere"
@@ -379,13 +504,29 @@ module Mongoid
         # @example Execute an $nin in a where query.
         #   selectable.where(:field.nin => [ 1, 2, 3 ])
         #
-        # @param [ Hash ] criterion The field/value criterion pairs.
+        # @param [ Hash ] condition The field/value criterion pairs.
         #
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def nin(criterion = nil)
-          send(strategy || :__intersect__, with_array_values(criterion), "$nin")
+        def nin(condition)
+          if condition.nil?
+            raise Errors::CriteriaArgumentRequired, :nin
+          end
+
+          condition = expand_condition_to_array_values(condition)
+
+          if strategy
+            send(strategy, condition, "$nin")
+          else
+            condition.inject(clone) do |query, (field, value)|
+              v = {'$nin' => value}
+              if negating?
+                v = {'$not' => v}
+              end
+              query.add_field_expression(field.to_s, v)
+            end.reset_strategies!
+          end
         end
         alias :not_in :nin
         key :nin, :intersect, "$nin"
@@ -395,13 +536,14 @@ module Mongoid
         # @example Add the $nor selection.
         #   selectable.nor(field: 1, field: 2)
         #
-        # @param [ Array ] criterion An array of hash criterion.
+        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
+        #   matches or Criteria objects.
         #
-        # @return [ Selectable ] The cloned selectable.
+        # @return [ Selectable ] The new selectable.
         #
         # @since 1.0.0
-        def nor(*criterion)
-          __multi__(criterion, "$nor")
+        def nor(*criteria)
+          _mongoid_add_top_level_operation('$nor', criteria)
         end
 
         # Is the current selectable negating the next selection?
@@ -416,9 +558,9 @@ module Mongoid
           !!negating
         end
 
-        # Negate the next selection.
+        # Negate the arguments, or the next selection if no arguments are given.
         #
-        # @example Negate the selection.
+        # @example Negate the next selection.
         #   selectable.not.in(field: [ 1, 2 ])
         #
         # @example Add the $not criterion.
@@ -427,34 +569,145 @@ module Mongoid
         # @example Execute a $not in a where query.
         #   selectable.where(:field.not => /Bob/)
         #
-        # @param [ Hash ] criterion The field/value pairs to negate.
+        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
+        #   matches or Criteria objects to negate.
         #
-        # @return [ Selectable ] The negated selectable.
+        # @return [ Selectable ] The new selectable.
         #
         # @since 1.0.0
-        def not(*criterion)
-          if criterion.empty?
+        def not(*criteria)
+          if criteria.empty?
             dup.tap { |query| query.negating = true }
           else
-            __override__(criterion.first, "$not")
+            criteria.compact.inject(self.clone) do |c, new_s|
+              if new_s.is_a?(Selectable)
+                new_s = new_s.selector
+              end
+              _mongoid_expand_keys(new_s).each do |k, v|
+                k = k.to_s
+                if c.selector[k] || k[0] == ?$
+                  c = c.send(:__multi__, [{'$nor' => [{k => v}]}], '$and')
+                else
+                  if v.is_a?(Hash)
+                    c = c.send(:__multi__, [{'$nor' => [{k => v}]}], '$and')
+                  else
+                    if v.is_a?(Regexp)
+                      negated_operator = '$not'
+                    else
+                      negated_operator = '$ne'
+                    end
+                    c = c.send(:__override__, {k => v}, negated_operator)
+                  end
+                end
+              end
+              c
+            end
           end
         end
         key :not, :override, "$not"
 
-        # Adds $or selection to the selectable.
+        # Creates a disjunction using $or from the existing criteria in the
+        # receiver and the provided arguments.
+        #
+        # This behavior (receiver becoming one of the disjunction operands)
+        # matches ActiveRecord's +or+ behavior.
+        #
+        # Use +any_of+ to add a disjunction of the arguments as an additional
+        # constraint to the criteria already existing in the receiver.
+        #
+        # Each argument can be a Hash, a Criteria object, an array of
+        # Hash or Criteria objects, or a nested array. Nested arrays will be
+        # flattened and can be of any depth. Passing arrays is deprecated.
         #
-        # @example Add the $or selection.
+        # @example Add the $or selection where both fields must have the specified values.
         #   selectable.or(field: 1, field: 2)
         #
-        # @param [ Array ] criterion An array of hash criterion.
+        # @example Add the $or selection where either value match is sufficient.
+        #   selectable.or({field: 1}, {field: 2})
         #
-        # @return [ Selectable ] The cloned selectable.
+        # @example Same as previous example but using the deprecated array wrap.
+        #   selectable.or([{field: 1}, {field: 2}])
+        #
+        # @example Same as previous example, also deprecated.
+        #   selectable.or([{field: 1}], [{field: 2}])
+        #
+        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        #   Multiple key/value pair matches or Criteria objects, or arrays
+        #   thereof. Passing arrays is deprecated.
+        #
+        # @return [ Selectable ] The new selectable.
+        #
+        # @since 1.0.0
+        def or(*criteria)
+          _mongoid_add_top_level_operation('$or', criteria)
+        end
+
+        # Adds a disjunction of the arguments as an additional constraint
+        # to the criteria already existing in the receiver.
+        #
+        # Use +or+ to make the receiver one of the disjunction operands.
+        #
+        # Each argument can be a Hash, a Criteria object, an array of
+        # Hash or Criteria objects, or a nested array. Nested arrays will be
+        # flattened and can be of any depth. Passing arrays is deprecated.
+        #
+        # @example Add the $or selection where both fields must have the specified values.
+        #   selectable.any_of(field: 1, field: 2)
+        #
+        # @example Add the $or selection where either value match is sufficient.
+        #   selectable.any_of({field: 1}, {field: 2})
+        #
+        # @example Same as previous example but using the deprecated array wrap.
+        #   selectable.any_of([{field: 1}, {field: 2}])
+        #
+        # @example Same as previous example, also deprecated.
+        #   selectable.any_of([{field: 1}], [{field: 2}])
+        #
+        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        #   Multiple key/value pair matches or Criteria objects, or arrays
+        #   thereof. Passing arrays is deprecated.
+        #
+        # @return [ Selectable ] The new selectable.
         #
         # @since 1.0.0
-        def or(*criterion)
-          __multi__(criterion, "$or")
+        def any_of(*criteria)
+          criteria = _mongoid_flatten_arrays(criteria)
+          case criteria.length
+          when 0
+            clone
+          when 1
+            # When we have a single criteria, any_of behaves like and.
+            # Note: criteria can be a Query object, which #where method does
+            # not support.
+            self.and(*criteria)
+          else
+            # When we have multiple criteria, combine them all with $or
+            # and add the result to self.
+            exprs = criteria.map do |criterion|
+              if criterion.is_a?(Selectable)
+                _mongoid_expand_keys(criterion.selector)
+              else
+                Hash[criterion.map do |k, v|
+                  if k.is_a?(Symbol)
+                    [k.to_s, v]
+                  else
+                    [k, v]
+                  end
+                end]
+              end
+            end
+            # Should be able to do:
+            #where('$or' => exprs)
+            # But since that is broken do instead:
+            clone.tap do |query|
+              if query.selector['$or']
+                query.selector.store('$or', query.selector['$or'] + exprs)
+              else
+                query.selector.store('$or', exprs)
+              end
+            end
+          end
         end
-        alias :any_of :or
 
         # Add a $size selection for array fields.
         #
@@ -472,7 +725,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def with_size(criterion = nil)
+        def with_size(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :with_size
+          end
+
           typed_override(criterion, "$size") do |value|
             ::Integer.evolve(value)
           end
@@ -496,7 +753,11 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def with_type(criterion = nil)
+        def with_type(criterion)
+          if criterion.nil?
+            raise Errors::CriteriaArgumentRequired, :with_type
+          end
+
           typed_override(criterion, "$type") do |value|
             ::Integer.evolve(value)
           end
@@ -527,21 +788,23 @@ module Mongoid
         #
         # @since 2.2.0
         def text_search(terms, opts = nil)
+          if terms.nil?
+            raise Errors::CriteriaArgumentRequired, :terms
+          end
+
           clone.tap do |query|
-            if terms
-              criterion = {'$text' => { '$search' => terms }}
-              criterion['$text'].merge!(opts) if opts
-              if query.selector['$text']
-                # Per https://docs.mongodb.com/manual/reference/operator/query/text/
-                # multiple $text expressions are not currently supported by
-                # MongoDB server, but build the query correctly instead of
-                # overwriting previous text search condition with the currently
-                # given one.
-                Mongoid.logger.warn('Multiple $text expressions per query are not currently supported by the server')
-                query.selector = {'$and' => [query.selector]}.merge(criterion)
-              else
-                query.selector = query.selector.merge(criterion)
-              end
+            criterion = {'$text' => { '$search' => terms }}
+            criterion['$text'].merge!(opts) if opts
+            if query.selector['$text']
+              # Per https://docs.mongodb.com/manual/reference/operator/query/text/
+              # multiple $text expressions are not currently supported by
+              # MongoDB server, but build the query correctly instead of
+              # overwriting previous text search condition with the currently
+              # given one.
+              Mongoid.logger.warn('Multiple $text expressions per query are not currently supported by the server')
+              query.selector = {'$and' => [query.selector]}.merge(criterion)
+            else
+              query.selector = query.selector.merge(criterion)
             end
           end
         end
@@ -561,18 +824,38 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
-        def where(criterion = nil)
-          # We need to save the criterion in an instance variable so Modifiable methods
-          # know how to create a polymorphic object.
-          @criterion = criterion
-          criterion.is_a?(String) ? js_query(criterion) : expr_query(criterion)
+        def where(*criteria)
+          criteria.inject(clone) do |query, criterion|
+            if criterion.nil?
+              raise Errors::CriteriaArgumentRequired, :where
+            end
+
+            # We need to save the criterion in an instance variable so
+            # Modifiable methods know how to create a polymorphic object.
+            # Note that this method in principle accepts multiple criteria,
+            # but only the first one will be stored in @criterion. This
+            # works out to be fine because first_or_create etc. methods
+            # only ever specify one criterion to #where.
+            @criterion = criterion
+            if criterion.is_a?(String)
+              js_query(criterion)
+            else
+              expr_query(criterion)
+            end
+          end.reset_strategies!
         end
 
         private
 
-        # Create the standard expression query.
+        # Adds the specified expression to the query.
         #
-        # @api private
+        # Criterion must be a hash in one of the following forms:
+        # - {field_name: value}
+        # - {'field_name' => value}
+        # - {key_instance: value}
+        # - {'$operator' => operator_value_expression}
+        #
+        # Field name and operator may be given as either strings or symbols.
         #
         # @example Create the selection.
         #   selectable.expr_query(age: 50)
@@ -582,9 +865,24 @@ module Mongoid
         # @return [ Selectable ] The cloned selectable.
         #
         # @since 1.0.0
+        # @api private
         def expr_query(criterion)
-          selection(criterion) do |selector, field, value|
-            selector.merge!(field.__expr_part__(value.__expand_complex__, negating?))
+          if criterion.nil?
+            raise ArgumentError, 'Criterion cannot be nil here'
+          end
+
+          clone.tap do |query|
+            criterion.each do |field, value|
+              field_s = field.to_s
+              if field_s[0] == ?$
+                # Query expression-level operator, like $and or $where
+                query.add_operator_expression(field_s, value)
+              else
+                exp_field, exp_value = expand_one_condition(field, value)
+                query.add_field_expression(exp_field, exp_value)
+              end
+            end
+            query.reset_strategies!
           end
         end
 
@@ -623,7 +921,13 @@ module Mongoid
         # @since 1.0.0
         def js_query(criterion)
           clone.tap do |query|
-            query.selector.merge!("$where" => criterion)
+            if negating?
+              query.add_operator_expression('$and',
+                [{'$nor' => [{'$where' => criterion}]}])
+            else
+              query.add_operator_expression('$where', criterion)
+            end
+            query.reset_strategies!
           end
         end
 
@@ -650,26 +954,6 @@ module Mongoid
           end
         end
 
-        # Convert the criterion values to $in friendly values. This means you,
-        # array.
-        #
-        # @api private
-        #
-        # @example Convert all the values to arrays.
-        #   selectable.with_array_values({ key: 1...4 })
-        #
-        # @param [ Hash ] criterion The criterion.
-        #
-        # @return [ Hash ] The $in friendly criterion (array values).
-        #
-        # @since 1.0.0
-        def with_array_values(criterion)
-          return nil unless criterion
-          criterion.each_pair do |key, value|
-            criterion[key] = value.__array__
-          end
-        end
-
         class << self
 
           # Get the methods on the selectable that can be forwarded to from a model.