mongoid 8.1.9 → 9.0.0

data/lib/mongoid/matcher/expression.rb

@@ -1,8 +1,21 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Base singleton module used for evaluating whether a given
+    # document in-memory matches an MSQL query expression.
+    #
     # @api private
     module Expression
+
+      # Returns whether a document satisfies a query expression.
+      #
+      # @param [ Mongoid::Document ] document The document.
+      # @param [ Hash ] expr The expression.
+      #
+      # @return [ true | false ] Whether the document matches.
+      #
+      # @api private
       module_function def matches?(document, expr)
         if expr.nil?
           raise Errors::InvalidQuery, "Nil condition in expression context"

data/lib/mongoid/matcher/expression_operator.rb

@@ -1,6 +1,10 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Singleton module provides lookup of logical query operator
+    # matchers.
+    #
     # @api private
     module ExpressionOperator
       MAP = {
@@ -9,6 +13,16 @@ module Mongoid
         '$or' => Or,
       }.freeze
 
+      # Returns the matcher module for a given operator.
+      #
+      # @param [ String ] op The operator name.
+      #
+      # @return [ Module ] The matcher module.
+      #
+      # @raises [ Mongoid::Errors::InvalidExpressionOperator ]
+      #   Raised if the given operator is unknown.
+      #
+      # @api private
       module_function def get(op)
         MAP.fetch(op)
       rescue KeyError

data/lib/mongoid/matcher/field_expression.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Singleton module used for evaluating whether a given
+    # value in-memory matches an MSQL query expression related
+    # to a specific field.
+    #
     # @api private
     module FieldExpression
+
+      # Returns whether a value satisfies a condition.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Hash | Object ] condition The condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         if condition.is_a?(Hash)
           condition.all? do |k, cond_v|

data/lib/mongoid/matcher/field_operator.rb

@@ -1,6 +1,10 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # Singleton module provides lookup of query operator matchers
+    # related to field values.
+    #
     # @api private
     module FieldOperator
       MAP = {
@@ -26,12 +30,27 @@ module Mongoid
         '$type' => Type,
       }.freeze
 
+      # Returns the matcher module for a given operator.
+      #
+      # @param [ String ] op The operator name.
+      #
+      # @return [ Module ] The matcher module.
+      #
+      # @raises [ Mongoid::Errors::InvalidFieldOperator ]
+      #   Raised if the given operator is unknown.
+      #
+      # @api private
       module_function def get(op)
         MAP.fetch(op)
       rescue KeyError
         raise Errors::InvalidFieldOperator.new(op)
       end
 
+      # Used for evaluating $lt, $lte, $gt, $gte comparison operators.
+      #
+      # @todo Refactor this as it is only relevant to $lt, $lte, $gt, $gte.
+      #
+      # @api private
       module_function def apply_array_field_operator(exists, value, condition)
         if Array === value
           value.any? { |v| yield v }
@@ -40,6 +59,11 @@ module Mongoid
         end
       end
 
+      # Used for evaluating $lt, $lte, $gt, $gte comparison operators.
+      #
+      # @todo Refactor this as it is only relevant to $lt, $lte, $gt, $gte.
+      #
+      # @api private
       module_function def apply_comparison_operator(operator, left, right)
         left.send(operator, right)
       rescue ArgumentError, NoMethodError, TypeError

data/lib/mongoid/matcher/gt.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $gt expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/gt/
+    #
     # @api private
     module Gt
+
+      # Returns whether a value satisfies a $gt expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Object ] condition The $gt condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         case condition
         when Range

data/lib/mongoid/matcher/gte.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $gte expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/gte/
+    #
     # @api private
     module Gte
+
+      # Returns whether a value satisfies a $gte expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Object ] condition The $gte condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         case condition
         when Range

data/lib/mongoid/matcher/in.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $in expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/in/
+    #
     # @api private
     module In
+
+      # Returns whether a value satisfies an $in expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ Object ] value The value to check.
+      # @param [ Array<Object> ] condition The $in condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         unless Array === condition
           raise Errors::InvalidQuery, "$in argument must be an array: #{Errors::InvalidQuery.truncate_expr(condition)}"

data/lib/mongoid/matcher/lt.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $lt expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/lt/
+    #
     # @api private
     module Lt
+
+      # Returns whether a value satisfies a $lt expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Object ] condition The $lt condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         case condition
         when Range

data/lib/mongoid/matcher/lte.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $lte expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/lte/
+    #
     # @api private
     module Lte
+
+      # Returns whether a value satisfies a $lte expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Object ] condition The $lte condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         case condition
         when Range

data/lib/mongoid/matcher/mod.rb

@@ -1,8 +1,24 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $mod expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/mod/
+    #
     # @api private
     module Mod
+
+      # Returns whether a value satisfies a $mod expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ Numeric ] value The value to check.
+      # @param [ Array<Numeric> ] condition The $mod condition predicate,
+      #   which is a 2-tuple containing the divisor and remainder.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         unless Array === condition
           raise Errors::InvalidQuery, "Unknown $mod argument #{condition}"

data/lib/mongoid/matcher/ne.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $ne expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/ne/
+    #
     # @api private
     module Ne
+
+      # Returns whether a value satisfies an $ne expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Object ] condition The $ne condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         case condition
         when ::Regexp, BSON::Regexp::Raw

data/lib/mongoid/matcher/nin.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $nin expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/nin/
+    #
     # @api private
     module Nin
+
+      # Returns whether a value satisfies a $nin expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Array<Object> ] condition The $nin condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         !In.matches?(exists, value, condition)
       end

data/lib/mongoid/matcher/nor.rb

@@ -1,8 +1,22 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $nor expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/nor/
+    #
     # @api private
     module Nor
+
+      # Returns whether a document satisfies a $nor expression.
+      #
+      # @param [ Mongoid::Document ] document The document.
+      # @param [ Array<Hash> ] expr The $nor conditions.
+      #
+      # @return [ true | false ] Whether the document matches.
+      #
+      # @api private
       module_function def matches?(document, expr)
         unless expr.is_a?(Array)
           raise Errors::InvalidQuery, "$nor argument must be an array: #{Errors::InvalidQuery.truncate_expr(expr)}"

data/lib/mongoid/matcher/not.rb

@@ -1,8 +1,24 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $not expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/not/
+    #
     # @api private
     module Not
+
+      # Returns whether a value satisfies an $not expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Hash | Regexp | BSON::Regexp::Raw ] condition
+      #   The $not condition predicate.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         case condition
         when ::Regexp, BSON::Regexp::Raw

data/lib/mongoid/matcher/or.rb

@@ -1,8 +1,22 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $or expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/or/
+    #
     # @api private
     module Or
+
+      # Returns whether a document satisfies an $or expression.
+      #
+      # @param [ Mongoid::Document ] document The document.
+      # @param [ Array<Hash> ] expr The $or conditions.
+      #
+      # @return [ true | false ] Whether the document matches.
+      #
+      # @api private
       module_function def matches?(document, expr)
         unless expr.is_a?(Array)
           raise Errors::InvalidQuery, "$or argument must be an array: #{Errors::InvalidQuery.truncate_expr(expr)}"

data/lib/mongoid/matcher/regex.rb

@@ -1,8 +1,23 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $regex expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/regex/
+    #
     # @api private
     module Regex
+
+      # Returns whether a value satisfies a $regex expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ String | Array<String> ] value The value to check.
+      # @param [ Regexp | BSON::Regexp::Raw ] condition The $regex condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         condition = case condition
         when Regexp
@@ -27,6 +42,15 @@ module Mongoid
         end
       end
 
+      # Returns whether an scalar or array value matches a Regexp.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ String | Array<String> ] value The value to check.
+      # @param [ Regexp ] condition The Regexp condition.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches_array_or_scalar?(value, condition)
         if Array === value
           value.any? do |v|

data/lib/mongoid/matcher/size.rb

@@ -1,8 +1,24 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $size expression.
+    #
+    # @see https://www.mongodb.com/docs/manual/reference/operator/query/size/
+    #
     # @api private
     module Size
+
+      # Returns whether a value satisfies a $size expression.
+      #
+      # @param [ true | false ] exists Not used.
+      # @param [ Numeric ] value The value to check.
+      # @param [ Integer | Array<Object> ] condition The $size condition
+      #   predicate, either a non-negative Integer or an Array to match size.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         case condition
         when Float

data/lib/mongoid/matcher/type.rb

@@ -1,10 +1,24 @@
+# rubocop:todo all
 module Mongoid
   module Matcher
 
+    # In-memory matcher for $type expression.
+    #
     # @see https://www.mongodb.com/docs/manual/reference/operator/query/type/
     #
     # @api private
     module Type
+
+      # Returns whether a value satisfies a $type expression.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Integer | Array<Integer> ] condition The $type condition
+      #   predicate which corresponds to the BSON type enumeration.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def matches?(exists, value, condition)
         conditions = case condition
         when Array
@@ -22,6 +36,17 @@ module Mongoid
         false
       end
 
+      # Returns whether a value satisfies a single $type expression
+      # value.
+      #
+      # @param [ true | false ] exists Whether the value exists.
+      # @param [ Object ] value The value to check.
+      # @param [ Integer ] condition The $type condition predicate
+      #   which corresponds to the BSON type enumeration.
+      #
+      # @return [ true | false ] Whether the value matches.
+      #
+      # @api private
       module_function def one_matches?(exists, value, condition)
         case condition
         when 1

data/lib/mongoid/matcher.rb

@@ -1,5 +1,9 @@
+# rubocop:todo all
 module Mongoid
 
+  # Utility module containing methods which assist in performing
+  # in-memory matching of documents with MQL query expressions.
+  #
   # @api private
   module Matcher
     # Extracts field values in the document at the specified key.
@@ -35,25 +39,11 @@ module Mongoid
     # from and behaves identically to association traversal for the purposes
     # of, for example, subsequent array element retrieval.
     #
-    # @param [ Document | Hash | String ] document The document to extract from.
+    # @param [ Document | Hash ] document The document to extract from.
     # @param [ String ] key The key path to extract.
     #
     # @return [ Object | Array ] Field value or values.
     module_function def extract_attribute(document, key)
-      # The matcher system will wind up sending atomic values to this as well,
-      # when attepting to match more complex types. If anything other than a
-      # Document or a Hash is given, we'll short-circuit the logic and just
-      # return an empty array.
-      return [] unless document.is_a?(Hash) || document.is_a?(Document)
-
-      # Performance optimization; if the key does not include a '.' character,
-      # it must reference an immediate attribute of the document.
-      unless key.include?('.')
-        hash = document.respond_to?(:attributes) ? document.attributes : document
-        key = find_exact_key(hash, key)
-        return key ? [ hash[key] ] : []
-      end
-
       if document.respond_to?(:as_attributes, true)
         # If a document has hash fields, as_attributes would keep those fields
         # as Hash instances which do not offer indifferent access.

data/lib/mongoid/persistable/creatable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Persistable
@@ -83,6 +84,7 @@ module Mongoid
       # @return [ true ] true.
       def post_process_insert
         self.new_record = false
+        remember_storage_options!
         flag_descendants_persisted
         true
       end
@@ -103,15 +105,18 @@ module Mongoid
         raise Errors::ReadonlyDocument.new(self.class) if readonly? && !Mongoid.legacy_readonly
         return self if performing_validations?(options) &&
           invalid?(options[:context] || :create)
-        run_callbacks(:save, with_children: false) do
-          run_callbacks(:create, with_children: false) do
-            run_callbacks(:persist_parent, with_children: false) do
-              _mongoid_run_child_callbacks(:save) do
-                _mongoid_run_child_callbacks(:create) do
-                  result = yield(self)
-                  if !result.is_a?(Document) || result.errors.empty?
-                    post_process_insert
-                    post_process_persist(result, options)
+        ensure_client_compatibility!
+        run_callbacks(:commit, with_children: true, skip_if: -> { in_transaction? }) do
+          run_callbacks(:save, with_children: false) do
+            run_callbacks(:create, with_children: false) do
+              run_callbacks(:persist_parent, with_children: false) do
+                _mongoid_run_child_callbacks(:save) do
+                  _mongoid_run_child_callbacks(:create) do
+                    result = yield(self)
+                    if !result.is_a?(Document) || result.errors.empty?
+                      post_process_insert
+                      post_process_persist(result, options)
+                    end
                   end
                 end
               end

data/lib/mongoid/persistable/deletable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Persistable
@@ -12,7 +13,11 @@ module Mongoid
       # @example Remove the document.
       #   document.remove
       #
-      # @param [ Hash ] options Options to pass to remove.
+      # @param [ Hash ] options The options.
+      # @option options [ true | false ] :persist Whether to persist
+      #   the delete action.
+      # @option options [ true | false ] :suppress Whether to update
+      #   the parent document in-memory when deleting an embedded document.
       #
       # @return [ TrueClass ] True.
       def delete(options = {})
@@ -99,7 +104,7 @@ module Mongoid
       #     collection.find(atomic_selector).remove
       #   end
       #
-      # @return [ Object ] The result of the block.
+      # @return [ true ] If the object was deleted successfully.
       def prepare_delete
         raise Errors::ReadonlyDocument.new(self.class) if readonly?
         yield(self)

data/lib/mongoid/persistable/destroyable.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+# rubocop:todo all
 
 module Mongoid
   module Persistable
@@ -12,25 +13,51 @@ module Mongoid
       # @example Destroy a document.
       #   document.destroy
       #
-      # @param [ Hash ] options Options to pass to destroy.
+      # @param [ Hash ] options The options.
+      # @option options [ true | false ] :persist Whether to persist
+      #   the delete action. Callbacks will still be run even if false.
+      # @option options [ true | false ] :suppress Whether to update
+      #   the parent document in-memory when deleting an embedded document.
       #
       # @return [ true | false ] True if successful, false if not.
       def destroy(options = nil)
         raise Errors::ReadonlyDocument.new(self.class) if readonly?
         self.flagged_for_destroy = true
-        result = run_callbacks(:destroy) do
-          if catch(:abort) { apply_destroy_dependencies! }
-            delete(options || {})
-          else
-            false
+        result = run_callbacks(:commit, skip_if: -> { in_transaction? }) do
+          run_callbacks(:destroy) do
+            if catch(:abort) { apply_destroy_dependencies! }
+              delete(options || {}).tap do |res|
+                if res && in_transaction?
+                  Threaded.add_modified_document(_session, self)
+                end
+              end
+            else
+              false
+            end
           end
         end
         self.flagged_for_destroy = false
         result
       end
 
+      # Remove the document from the database with callbacks. Raises
+      # an error if the document is not destroyed.
+      #
+      # @example Destroy a document.
+      #   document.destroy!
+      #
+      # @param [ Hash ] options The options.
+      # @option options [ true | false ] :persist Whether to persist
+      #   the delete action. Callbacks will still be run even if false.
+      # @option options [ true | false ] :suppress Whether to update
+      #   the parent document in-memory when deleting an embedded document.
+      #
+      # @raises [ Mongoid::Errors::DocumentNotDestroyed ] Raised if
+      #   the document was not destroyed.
+      #
+      # @return [ true ] Always true.
       def destroy!(options = {})
-        destroy || raise(Errors::DocumentNotDestroyed.new(_id, self.class))
+        destroy(options) || raise(Errors::DocumentNotDestroyed.new(_id, self.class))
       end
 
       module ClassMethods