mongoid 8.0.3 → 8.1.0

data/lib/mongoid/contextual/none.rb

@@ -80,15 +80,24 @@ module Mongoid
       # @example Do any documents exist in the null context.
       #   context.exists?
       #
+      # @example Do any documents exist for given _id.
+      #   context.exists?(BSON::ObjectId(...))
+      #
+      # @example Do any documents exist for given conditions.
+      #   context.exists?(name: "...")
+      #
+      # @param [ Hash | Object | false ] id_or_conditions an _id to
+      #   search for, a hash of conditions, nil or false.
+      #
       # @return [ false ] Always false.
-      def exists?; false; end
+      def exists?(id_or_conditions = :none); false; end
 
       # Pluck the field values in null context.
       #
       # @example Get the values for null context.
       #   context.pluck(:name)
       #
-      # @param [ String | Symbol ] *_fields Field(s) to pluck.
+      # @param [ [ String | Symbol ]... ] *_fields Field(s) to pluck.
       #
       # @return [ Array ] An empty Array.
       def pluck(*_fields)
@@ -100,9 +109,9 @@ module Mongoid
       # @example Get the value for null context.
       #   context.pick(:name)
       #
-      # @param [ String | Symbol ] *_fields Field or fields to pick.
+      # @param [ [ String | Symbol ]... ] *_fields Field(s) to pick.
       #
-      # @return [ nil ] Always reeturn nil.
+      # @return [ nil ] Always return nil.
       def pick(*_fields)
         nil
       end
@@ -136,11 +145,21 @@ module Mongoid
       #
       # @param [ Integer ] limit The number of documents to return.
       #
-      # @return [ nil ] Always nil.
+      # @return [ [] | nil ] Empty array or nil.
       def first(limit = nil)
         [] unless limit.nil?
       end
 
+      # Always raises an error.
+      #
+      # @example Get the first document in null context.
+      #   context.first!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def first!
+        raise_document_not_found_error
+      end
+
       # Always returns nil.
       #
       # @example Get the last document in null context.
@@ -148,11 +167,21 @@ module Mongoid
       #
       # @param [ Integer ] limit The number of documents to return.
       #
-      # @return [ nil ] Always nil.
+      # @return [ [] | nil ] Empty array or nil.
       def last(limit = nil)
         [] unless limit.nil?
       end
 
+      # Always raises an error.
+      #
+      # @example Get the last document in null context.
+      #   context.last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def last!
+        raise_document_not_found_error
+      end
+
       # Returns nil or empty array.
       #
       # @example Take a document in null context.
@@ -172,7 +201,127 @@ module Mongoid
       #
       # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
       def take!
-        raise Errors::DocumentNotFound.new(klass, nil, nil)
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the second document in null context.
+      #   context.second
+      #
+      # @return [ nil ] Always nil.
+      def second
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the second document in null context.
+      #   context.second!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def second!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the third document in null context.
+      #   context.third
+      #
+      # @return [ nil ] Always nil.
+      def third
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the third document in null context.
+      #   context.third!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def third!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the fourth document in null context.
+      #   context.fourth
+      #
+      # @return [ nil ] Always nil.
+      def fourth
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the fourth document in null context.
+      #   context.fourth!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def fourth!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the fifth document in null context.
+      #   context.fifth
+      #
+      # @return [ nil ] Always nil.
+      def fifth
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the fifth document in null context.
+      #   context.fifth!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def fifth!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the second to last document in null context.
+      #   context.second_to_last
+      #
+      # @return [ nil ] Always nil.
+      def second_to_last
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the second to last document in null context.
+      #   context.second_to_last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def second_to_last!
+        raise_document_not_found_error
+      end
+
+      # Always returns nil.
+      #
+      # @example Get the third to last document in null context.
+      #   context.third_to_last
+      #
+      # @return [ nil ] Always nil.
+      def third_to_last
+        nil
+      end
+
+      # Always raises an error.
+      #
+      # @example Get the third to last document in null context.
+      #   context.third_to_last!
+      #
+      # @raises [ Mongoid::Errors::DocumentNotFound ] always raises.
+      def third_to_last!
+        raise_document_not_found_error
       end
 
       # Always returns zero.
@@ -188,6 +337,12 @@ module Mongoid
 
       alias :find_first :first
       alias :one :first
+
+      private
+
+      def raise_document_not_found_error
+        raise Errors::DocumentNotFound.new(klass, nil, nil)
+      end
     end
   end
 end

data/lib/mongoid/contextual.rb

@@ -35,6 +35,18 @@ module Mongoid
       @context ||= create_context
     end
 
+    # Instructs the context to schedule an asynchronous loading of documents
+    # specified by the criteria.
+    #
+    # Note that depending on the context and on the Mongoid configuration,
+    # documents can be loaded synchronously on the caller's thread.
+    #
+    # @return [ Criteria ] Returns self.
+    def load_async
+      context.load_async if context.respond_to?(:load_async)
+      self
+    end
+
     private
 
     # Create the context for the queries to execute. Will be memory for

data/lib/mongoid/criteria/findable.rb

@@ -21,7 +21,7 @@ module Mongoid
         multi ? result : result.first
       end
 
-      # Find the matchind document(s) in the criteria for the provided ids.
+      # Find the matching document(s) in the criteria for the provided id(s).
       #
       # @note Each argument can be an individual id, an array of ids or
       #   a nested array. Each array will be flattened.
@@ -32,7 +32,7 @@ module Mongoid
       # @example Find by multiple ids.
       #   criteria.find([ BSON::ObjectId.new, BSON::ObjectId.new ])
       #
-      # @param [ Object | Array<Object> ] *args The ids to search for.
+      # @param [ [ Object | Array<Object> ]... ] *args The id(s) to find.
       #
       # @return [ Document | Array<Document> ] The matching document(s).
       def find(*args)

data/lib/mongoid/criteria/includable.rb

@@ -21,8 +21,8 @@ module Mongoid
       # @example Eager load the provided associations.
       #   Person.includes(:posts, :game)
       #
-      # @param [ Array<Symbol>, Array<Hash> ] relations The names of the associations to eager
-      #   load.
+      # @param [ [ Symbol | Hash ]... ] *relations The names of the association(s)
+      #   to eager load.
       #
       # @return [ Criteria ] The cloned criteria.
       def includes(*relations)
@@ -70,7 +70,8 @@ module Mongoid
       #   association originates.
       # @param [ String ] parent The name of the association above this one in
       #   the inclusion tree, if it is a nested inclusion.
-      # @param relations_list The names of the associations to eager load.
+      # @param [ [ Symbol | Hash | Array<Symbol | Hash> ]... ] *relations_list
+      #   The names of the association(s) to eager load.
       def extract_includes_list(_parent_class, parent, *relations_list)
         relations_list.flatten.each do |relation_object|
           if relation_object.is_a?(Hash)

data/lib/mongoid/criteria/queryable/extensions/array.rb

@@ -105,7 +105,7 @@ module Mongoid
           #
           # @return [ Hash ] The field/direction pair.
           def __sort_pair__
-            { first => last.to_direction }
+            { first => Mongoid::Criteria::Translator.to_direction(last) }
           end
 
           private

data/lib/mongoid/criteria/queryable/extensions/hash.rb

@@ -115,7 +115,7 @@ module Mongoid
           def __sort_option__
             tap do |hash|
               hash.each_pair do |key, value|
-                hash.store(key, value.to_direction)
+                hash.store(key, Mongoid::Criteria::Translator.to_direction(value))
               end
             end
           end

data/lib/mongoid/criteria/queryable/extensions/numeric.rb

@@ -30,14 +30,6 @@ module Mongoid
             ::Time.at(self).utc
           end
 
-          # Get the integer as a sort direction.
-          #
-          # @example Get the integer as a sort direction.
-          #   1.to_direction
-          #
-          # @return [ Integer ] self.
-          def to_direction; self; end
-
           module ClassMethods
 
             # Get the object as a numeric.

data/lib/mongoid/criteria/queryable/extensions/string.rb

@@ -49,7 +49,7 @@ module Mongoid
             split(/,/).inject({}) do |hash, spec|
               hash.tap do |_hash|
                 field, direction = spec.strip.split(/\s/)
-                _hash[field.to_sym] = direction.to_direction
+                _hash[field.to_sym] = Mongoid::Criteria::Translator.to_direction(direction)
               end
             end
           end
@@ -67,16 +67,6 @@ module Mongoid
             ::String.__expr_part__(self, value, negating)
           end
 
-          # Get the string as a sort direction.
-          #
-          # @example Get the string as a sort direction.
-          #   "1".to_direction
-          #
-          # @return [ Integer ] The direction.
-          def to_direction
-            self =~ /desc/i ? -1 : 1
-          end
-
           module ClassMethods
 
             # Get the value as a expression.

data/lib/mongoid/criteria/queryable/extensions/symbol.rb

@@ -21,16 +21,6 @@ module Mongoid
             ::String.__expr_part__(self, value, negating)
           end
 
-          # Get the symbol as a sort direction.
-          #
-          # @example Get the symbol as a sort direction.
-          #   "1".to_direction
-          #
-          # @return [ Integer ] The direction.
-          def to_direction
-            to_s.to_direction
-          end
-
           module ClassMethods
 
             # Adds a method on symbol as a convenience for the MongoDB operator.

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

@@ -91,7 +91,7 @@ module Mongoid
 
         # Calculate the hash code for a key.
         #
-        # @return [ Fixnum ] The hash code for the key.
+        # @return [ Integer ] The hash code for the key.
         def hash
           [name, operator, expanded].hash
         end

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

@@ -283,7 +283,7 @@ module Mongoid
                     # The new value is a simple value.
                     # Transform the implicit equality to either $eq or $regexp
                     # depending on the type of the argument. See
-                    # https://docs.mongodb.com/manual/reference/operator/query/eq/#std-label-eq-usage-examples
+                    # https://www.mongodb.com/docs/manual/reference/operator/query/eq/#std-label-eq-usage-examples
                     # for the description of relevant server behavior.
                     op = case v
                     when Regexp, BSON::Regexp::Raw

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

@@ -17,7 +17,7 @@ module Mongoid
         # @example Add ascending sorting.
         #   optional.ascending(:first_name, :last_name)
         #
-        # @param [ Array<Symbol> ] fields The fields to sort.
+        # @param [ Symbol... ] *fields The field(s) to sort.
         #
         # @return [ Optional ] The cloned optional.
         def ascending(*fields)
@@ -45,7 +45,7 @@ module Mongoid
         # @example Add descending sorting.
         #   optional.descending(:first_name, :last_name)
         #
-        # @param [ Array<Symbol> ] fields The fields to sort.
+        # @param [ Symbol... ] *fields The field(s) to sort.
         #
         # @return [ Optional ] The cloned optional.
         def descending(*fields)
@@ -123,7 +123,7 @@ module Mongoid
         # @example Limit the results to the provided fields.
         #   optional.only(:name, :dob)
         #
-        # @param [ Array<Symbol> ] args The fields to return.
+        # @param [ Symbol... ] *args The field(s) to return.
         #
         # @return [ Optional ] The cloned optional.
         def only(*args)
@@ -163,7 +163,7 @@ module Mongoid
         # @example Add sorting options via a string.
         #   optional.order_by("name ASC, dob DESC")
         #
-        # @param [ Array | Hash | String ] spec The sorting specification.
+        # @param [ [ Array | Hash | String ]... ] *spec The sorting specification.
         #
         # @return [ Optional ] The cloned optional.
         def order_by(*spec)
@@ -184,7 +184,7 @@ module Mongoid
         # @example Replace the ordering.
         #   optional.reorder(name: :asc)
         #
-        # @param [ Array | Hash | String ] spec The sorting specification.
+        # @param [ [ Array | Hash | String ]... ] *spec The sorting specification.
         #
         # @return [ Optional ] The cloned optional.
         def reorder(*spec)
@@ -245,7 +245,7 @@ module Mongoid
         # @example Limit the results to the fields not provided.
         #   optional.without(:name, :dob)
         #
-        # @param [ Array<Symbol> ] args The fields to ignore.
+        # @param [ Symbol... ] *args The field(s) to ignore.
         #
         # @return [ Optional ] The cloned optional.
         def without(*args)
@@ -331,7 +331,7 @@ module Mongoid
         # @example Store the option.
         #   optional.option({ skip: 10 })
         #
-        # @param [ Array ] args The options.
+        # @param [ Object... ] *args The options.
         #
         # @return [ Queryable ] The cloned queryable.
         def option(*args)
@@ -349,7 +349,7 @@ module Mongoid
         # @example Add multiple sort options.
         #   optional.sort_with_list(:name, :dob, 1)
         #
-        # @param [ Array<String> ] fields The field names.
+        # @param [ [ Symbol | String ]... ] *fields The field name(s).
         # @param [ Integer ] direction The sort direction.
         #
         # @return [ Optional ] The cloned optional.

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

@@ -31,7 +31,7 @@ module Mongoid
         # @example Execute an $all in a where query.
         #   selectable.where(:field.all => [ 1, 2 ])
         #
-        # @param [ Hash ] criterion The key value pairs for $all matching.
+        # @param [ Hash... ] *criteria The key value pair(s) for $all matching.
         #
         # @return [ Selectable ] The cloned selectable.
         def all(*criteria)
@@ -69,8 +69,9 @@ module Mongoid
         # @example Add the criterion.
         #   selectable.and({ field: value }, { other: value })
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
-        #   matches or Criteria objects that all must match to return results.
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
+        #   Multiple key/value pair matches or Criteria objects that all must
+        #   match to return results.
         #
         # @return [ Selectable ] The new selectable.
         def and(*criteria)
@@ -199,7 +200,7 @@ module Mongoid
         #   the upper right (north east) as the second argument.
         #   Important: When latitude and longitude are passed, longitude is
         #   expected as the first element of the coordinate pair.
-        #   Source: https://docs.mongodb.com/manual/reference/operator/query/box/
+        #   Source: https://www.mongodb.com/docs/manual/reference/operator/query/box/
         #
         # @example Add a geo intersect criterion for a line.
         #   query.geo_spatial(:location.intersects_line => [[ 1, 10 ], [ 2, 10 ]])
@@ -516,8 +517,8 @@ module Mongoid
         # @example Add the $nor selection.
         #   selectable.nor(field: 1, field: 2)
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
-        #   matches or Criteria objects.
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
+        #   Multiple key/value pair matches or Criteria objects.
         #
         # @return [ Selectable ] The new selectable.
         def nor(*criteria)
@@ -545,7 +546,7 @@ module Mongoid
         # @example Execute a $not in a where query.
         #   selectable.where(:field.not => /Bob/)
         #
-        # @param [ Array<Hash | Criteria> ] criteria Multiple key/value pair
+        # @param [ [ Hash | Criteria ]... ] *criteria The key/value pair
         #   matches or Criteria objects to negate.
         #
         # @return [ Selectable ] The new selectable.
@@ -580,6 +581,35 @@ module Mongoid
         end
         key :not, :override, "$not"
 
+        # Negate the arguments, constraining the query to only those documents
+        # that do NOT match the arguments.
+        #
+        # @example Exclude a single criterion.
+        #   selectable.none_of(name: /Bob/)
+        #
+        # @example Exclude multiple criteria.
+        #   selectable.none_of(name: /Bob/, country: "USA")
+        #
+        # @example Exclude multiple criteria as an array.
+        #   selectable.none_of([{ name: /Bob/ }, { country: "USA" }])
+        #
+        # @param [ [ Hash | Criteria ]... ] *criteria The key/value pair
+        #   matches or Criteria objects to negate.
+        #
+        # @return [ Selectable ] The new selectable.
+        def none_of(*criteria)
+          criteria = _mongoid_flatten_arrays(criteria)
+          return dup if criteria.empty?
+
+          exprs = criteria.map do |criterion|
+            _mongoid_expand_keys(
+                criterion.is_a?(Selectable) ?
+                  criterion.selector : criterion)
+          end
+
+          self.and('$nor' => exprs)
+        end
+
         # Creates a disjunction using $or from the existing criteria in the
         # receiver and the provided arguments.
         #
@@ -605,7 +635,7 @@ module Mongoid
         # @example Same as previous example, also deprecated.
         #   selectable.or([{field: 1}], [{field: 2}])
         #
-        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
         #   Multiple key/value pair matches or Criteria objects, or arrays
         #   thereof. Passing arrays is deprecated.
         #
@@ -635,7 +665,7 @@ module Mongoid
         # @example Same as previous example, also deprecated.
         #   selectable.any_of([{field: 1}], [{field: 2}])
         #
-        # @param [ Hash | Criteria | Array<Hash | Criteria>, ... ] criteria
+        # @param [ [ Hash | Criteria | Array<Hash | Criteria> ]... ] *criteria
         #   Multiple key/value pair matches or Criteria objects, or arrays
         #   thereof. Passing arrays is deprecated.
         #
@@ -731,7 +761,7 @@ module Mongoid
         # @example Construct a text search selector with options.
         #   selectable.text_search("testing", :$language => "fr")
         #
-        # @note Per https://docs.mongodb.com/manual/reference/operator/query/text/
+        # @note Per https://www.mongodb.com/docs/manual/reference/operator/query/text/
         #   it is not currently possible to supply multiple text search
         #   conditions in a query. Mongoid will build such a query but the
         #   server will return an error when trying to execute it.
@@ -751,7 +781,7 @@ module Mongoid
             criterion = {'$text' => { '$search' => terms }}
             criterion['$text'].merge!(opts) if opts
             if query.selector['$text']
-              # Per https://docs.mongodb.com/manual/reference/operator/query/text/
+              # Per https://www.mongodb.com/docs/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
@@ -774,7 +804,8 @@ module Mongoid
         # @example Add a javascript selection.
         #   selectable.where("this.name == 'syd'")
         #
-        # @param [ String | Hash ] criterion The javascript or standard selection.
+        # @param [ [ Hash | String ]... ] *criterion The standard selection
+        #   or javascript string.
         #
         # @return [ Selectable ] The cloned selectable.
         def where(*criteria)

data/lib/mongoid/criteria/translator.rb

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

data/lib/mongoid/criteria.rb

@@ -8,6 +8,7 @@ require "mongoid/criteria/modifiable"
 require "mongoid/criteria/queryable"
 require "mongoid/criteria/scopable"
 require "mongoid/criteria/options"
+require "mongoid/criteria/translator"
 
 module Mongoid
 
@@ -88,7 +89,7 @@ module Mongoid
     # @example Tries to find a document whose _id is the stringification of the provided Proc, typically failing.
     #   enumerator = criteria.find(-> { "Default Band" })
     #
-    # @param [ Object | Array<Object> ] *args The ids.
+    # @param [ [ Object | Array<Object> ]... ] *args The id(s).
     # @param [ Proc ] block Optional block to pass.
     #
     # @return [ Document | Array<Document> | nil ] A document or matching documents.
@@ -284,7 +285,7 @@ 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.
     def only(*args)
@@ -318,7 +319,7 @@ 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.
     def without(*args)
@@ -385,7 +386,8 @@ 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.
@@ -495,7 +497,7 @@ 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.
     ruby2_keywords def method_missing(name, *args, &block)