mongoid 8.0.5 → 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/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.rb

@@ -89,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.
@@ -285,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)
@@ -319,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)
@@ -386,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.
@@ -496,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)

data/lib/mongoid/deprecable.rb

@@ -24,7 +24,7 @@ module Mongoid
     #   #=> 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
+    # @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)

data/lib/mongoid/errors/create_collection_failure.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an attempt to create a collection failed.
+    class CreateCollectionFailure < MongoidError
+
+      # Instantiate the create collection error.
+      #
+      # @param [ String ] collection_name The name of the collection that
+      #   Mongoid failed to create.
+      # @param [ Hash ] collection_options The options that were used when
+      #   tried to create the collection.
+      # @param [ Mongo::Error::OperationFailure ] error The error raised when
+      #   tried to create the collection.
+      #
+      # @api private
+      def initialize(collection_name, collection_options, error)
+        super(
+            compose_message(
+                "create_collection_failure",
+                {
+                  collection_name: collection_name,
+                  collection_options: collection_options,
+                  error: "#{error.class}: #{error.message}"
+                }
+            )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/drop_collection_failure.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # Raised when an attempt to drop a collection failed.
+    class DropCollectionFailure < MongoidError
+
+      # Instantiate the drop collection error.
+      #
+      # @param [ String ] collection_name The name of the collection that
+      #   Mongoid failed to drop.
+      #
+      # @api private
+      def initialize(collection_name, collection_options, error)
+        super(
+            compose_message(
+                "drop_collection_failure",
+                {
+                  collection_name: collection_name
+                }
+            )
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/immutable_attribute.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when attempting the change the value of an
+    # immutable attribute. For example, the _id attribute is immutable,
+    # and attempting to change it on a document that has already been
+    # persisted will result in this error.
+    class ImmutableAttribute < MongoidError
+
+      # Create the new error.
+      #
+      # @example Create the new error.
+      #   ImmutableAttribute.new(:_id, "1234")
+      #
+      # @param [ Symbol | String ] name The name of the attribute.
+      # @param [ Object ] value The attempted set value.
+      def initialize(name, value)
+        super(
+          compose_message("immutable_attribute", { name: name, value: value })
+        )
+      end
+    end
+  end
+end

data/lib/mongoid/errors/invalid_async_query_executor.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Mongoid
+  module Errors
+
+    # This error is raised when a bad async query executor option is attempted
+    # to be set.
+    class InvalidQueryExecutor < MongoidError
+
+      # Create the new error.
+      #
+      # @param [ Symbol | String ] executor The attempted async query executor.
+      #
+      # @api private
+      def initialize(executor)
+        super(
+          compose_message(
+            "invalid_async_query_executor",
+            { executor: executor, options: [:immediate, :global_thread_pool] }
+          )
+        )
+      end
+    end
+  end
+end