mongoid_rails4 4.0.0

data/lib/mongoid/contextual/memory.rb

@@ -0,0 +1,440 @@
+# encoding: utf-8
+require "mongoid/contextual/aggregable/memory"
+
+module Mongoid
+  module Contextual
+    class Memory
+      include Enumerable
+      include Aggregable::Memory
+      include Eager
+      include Queryable
+      include Positional
+
+      # @attribute [r] root The root document.
+      # @attribute [r] path The atomic path.
+      # @attribute [r] selector The root document selector.
+      # @attribute [r] matching The in memory documents that match the selector.
+      attr_reader :documents, :path, :root, :selector
+
+      # Check if the context is equal to the other object.
+      #
+      # @example Check equality.
+      #   context == []
+      #
+      # @param [ Array ] other The other array.
+      #
+      # @return [ true, false ] If the objects are equal.
+      #
+      # @since 3.0.0
+      def ==(other)
+        return false unless other.respond_to?(:entries)
+        entries == other.entries
+      end
+
+      # Delete all documents in the database that match the selector.
+      #
+      # @example Delete all the documents.
+      #   context.delete
+      #
+      # @return [ nil ] Nil.
+      #
+      # @since 3.0.0
+      def delete
+        deleted = count
+        removed = map do |doc|
+          prepare_remove(doc)
+          doc.as_document
+        end
+        unless removed.empty?
+          collection.find(selector).update(
+            positionally(selector, "$pullAll" => { path => removed })
+          )
+        end
+        deleted
+      end
+      alias :delete_all :delete
+
+      # Destroy all documents in the database that match the selector.
+      #
+      # @example Destroy all the documents.
+      #   context.destroy
+      #
+      # @return [ nil ] Nil.
+      #
+      # @since 3.0.0
+      def destroy
+        deleted = count
+        each do |doc|
+          documents.delete_one(doc)
+          doc.destroy
+        end
+        deleted
+      end
+      alias :destroy_all :destroy
+
+      # Get the distinct values in the db for the provided field.
+      #
+      # @example Get the distinct values.
+      #   context.distinct(:name)
+      #
+      # @param [ String, Symbol ] field The name of the field.
+      #
+      # @return [ Array<Object> ] The distinct values for the field.
+      #
+      # @since 3.0.0
+      def distinct(field)
+        documents.map{ |doc| doc.send(field) }.uniq
+      end
+
+      # Iterate over the context. If provided a block, yield to a Mongoid
+      # document for each, otherwise return an enum.
+      #
+      # @example Iterate over the context.
+      #   context.each do |doc|
+      #     puts doc.name
+      #   end
+      #
+      # @return [ Enumerator ] The enumerator.
+      #
+      # @since 3.0.0
+      def each
+        if block_given?
+          documents_for_iteration.each do |doc|
+            yield(doc)
+          end
+          # eager_loadable? ? docs : self
+        else
+          to_enum
+        end
+      end
+
+      # Do any documents exist for the context.
+      #
+      # @example Do any documents exist for the context.
+      #   context.exists?
+      #
+      # @return [ true, false ] If the count is more than zero.
+      #
+      # @since 3.0.0
+      def exists?
+        count > 0
+      end
+
+      # Get the first document in the database for the criteria's selector.
+      #
+      # @example Get the first document.
+      #   context.first
+      #
+      # @return [ Document ] The first document.
+      #
+      # @since 3.0.0
+      def first
+        doc = documents.first
+        eager_load_one(doc) if eager_loadable?(doc)
+        doc
+      end
+      alias :one :first
+
+      # Create the new in memory context.
+      #
+      # @example Create the new context.
+      #   Memory.new(criteria)
+      #
+      # @param [ Criteria ] The criteria.
+      #
+      # @since 3.0.0
+      def initialize(criteria)
+        @criteria, @klass = criteria, criteria.klass
+        @documents = criteria.documents.select do |doc|
+          @root ||= doc._root
+          @collection ||= root.collection
+          doc.matches?(criteria.selector)
+        end
+        apply_sorting
+        apply_options
+      end
+
+      # Get the last document in the database for the criteria's selector.
+      #
+      # @example Get the last document.
+      #   context.last
+      #
+      # @return [ Document ] The last document.
+      #
+      # @since 3.0.0
+      def last
+        doc = documents.last
+        eager_load_one(doc) if eager_loadable?(doc)
+        doc
+      end
+
+      # Get the length of matching documents in the context.
+      #
+      # @example Get the length of matching documents.
+      #   context.length
+      #
+      # @return [ Integer ] The matching length.
+      #
+      # @since 3.0.0
+      def length
+        documents.length
+      end
+      alias :size :length
+
+      # Limits the number of documents that are returned.
+      #
+      # @example Limit the documents.
+      #   context.limit(20)
+      #
+      # @param [ Integer ] value The number of documents to return.
+      #
+      # @return [ Mongo ] The context.
+      #
+      # @since 3.0.0
+      def limit(value)
+        self.limiting = value
+        self
+      end
+
+      # Skips the provided number of documents.
+      #
+      # @example Skip the documents.
+      #   context.skip(20)
+      #
+      # @param [ Integer ] value The number of documents to skip.
+      #
+      # @return [ Mongo ] The context.
+      #
+      # @since 3.0.0
+      def skip(value)
+        self.skipping = value
+        self
+      end
+
+      # Sorts the documents by the provided spec.
+      #
+      # @example Sort the documents.
+      #   context.sort(name: -1, title: 1)
+      #
+      # @param [ Hash ] values The sorting values as field/direction(1/-1)
+      #   pairs.
+      #
+      # @return [ Mongo ] The context.
+      #
+      # @since 3.0.0
+      def sort(values)
+        in_place_sort(values) and self
+      end
+
+      # Update the first matching document atomically.
+      #
+      # @example Update the matching document.
+      #   context.update(name: "Smiths")
+      #
+      # @param [ Hash ] attributes The new attributes for the document.
+      #
+      # @return [ nil, false ] False if no attributes were provided.
+      #
+      # @since 3.0.0
+      def update(attributes = nil)
+        update_documents(attributes, [ first ])
+      end
+
+      # Update all the matching documents atomically.
+      #
+      # @example Update all the matching documents.
+      #   context.update_all(name: "Smiths")
+      #
+      # @param [ Hash ] attributes The new attributes for each document.
+      #
+      # @return [ nil, false ] False if no attributes were provided.
+      #
+      # @since 3.0.0
+      def update_all(attributes = nil)
+        update_documents(attributes, entries)
+      end
+
+      private
+
+      # Get the documents the context should iterate. This follows 3 rules:
+      #
+      # @api private
+      #
+      # @example Get the documents for iteration.
+      #   context.documents_for_iteration
+      #
+      # @return [ Array<Document> ] The docs to iterate.
+      #
+      # @since 3.1.0
+      def documents_for_iteration
+        docs = documents[skipping || 0, limiting || documents.length] || []
+        if eager_loadable?
+          eager_load(docs)
+        end
+        docs
+      end
+
+      # Update the provided documents with the attributes.
+      #
+      # @api private
+      #
+      # @example Update the documents.
+      #   context.update_documents({}, doc)
+      #
+      # @param [ Hash ] attributes The attributes.
+      # @param [ Array<Document> ] docs The docs to update.
+      #
+      # @since 3.0.4
+      def update_documents(attributes, docs)
+        return false if !attributes || docs.empty?
+        updates = { "$set" => {}}
+        docs.each do |doc|
+          @selector ||= root.atomic_selector
+          doc.write_attributes(attributes)
+          updates["$set"].merge!(doc.atomic_updates["$set"] || {})
+          doc.move_changes
+        end
+        collection.find(selector).update(updates)
+      end
+
+      # Get the limiting value.
+      #
+      # @api private
+      #
+      # @example Get the limiting value.
+      #
+      # @return [ Integer ] The limit.
+      #
+      # @since 3.0.0
+      def limiting
+        defined?(@limiting) ? @limiting : nil
+      end
+
+      # Set the limiting value.
+      #
+      # @api private
+      #
+      # @example Set the limiting value.
+      #
+      # @param [ Integer ] value The limit.
+      #
+      # @return [ Integer ] The limit.
+      #
+      # @since 3.0.0
+      def limiting=(value)
+        @limiting = value
+      end
+
+      # Get the skiping value.
+      #
+      # @api private
+      #
+      # @example Get the skiping value.
+      #
+      # @return [ Integer ] The skip.
+      #
+      # @since 3.0.0
+      def skipping
+        defined?(@skipping) ? @skipping : nil
+      end
+
+      # Set the skiping value.
+      #
+      # @api private
+      #
+      # @example Set the skiping value.
+      #
+      # @param [ Integer ] value The skip.
+      #
+      # @return [ Integer ] The skip.
+      #
+      # @since 3.0.0
+      def skipping=(value)
+        @skipping = value
+      end
+
+      # Apply criteria options.
+      #
+      # @api private
+      #
+      # @example Apply criteria options.
+      #   context.apply_options
+      #
+      # @return [ Memory ] self.
+      #
+      # @since 3.0.0
+      def apply_options
+        skip(criteria.options[:skip]).limit(criteria.options[:limit])
+      end
+
+      # Map the sort symbols to the correct MongoDB values.
+      #
+      # @example Apply the sorting params.
+      #   context.apply_sorting
+      #
+      # @since 3.0.0
+      def apply_sorting
+        if spec = criteria.options[:sort]
+          in_place_sort(spec)
+        end
+      end
+
+      # Compare two values, checking for nil.
+      #
+      # @api private
+      #
+      # @example Compare the two objects.
+      #   context.compare(a, b)
+      #
+      # @param [ Object ] a The first object.
+      # @param [ Object ] b The first object.
+      #
+      # @return [ Integer ] The comparison value.
+      #
+      # @since 3.0.0
+      def compare(a, b)
+        case
+        when a.nil? then b.nil? ? 0 : 1
+        when b.nil? then -1
+        else a <=> b
+        end
+      end
+
+      # Sort the documents in place.
+      #
+      # @example Sort the documents.
+      #   context.in_place_sort(name: 1)
+      #
+      # @param [ Hash ] values The field/direction sorting pairs.
+      #
+      # @since 3.0.0
+      def in_place_sort(values)
+        values.keys.reverse.each do |field|
+          documents.sort! do |a, b|
+            a_value, b_value = a[field], b[field]
+            value = compare(a_value.__sortable__, b_value.__sortable__)
+            values[field] < 0 ? value * -1 : value
+          end
+        end
+      end
+
+      # Prepare the document for batch removal.
+      #
+      # @api private
+      #
+      # @example Prepare for removal.
+      #   context.prepare_remove(doc)
+      #
+      # @param [ Document ] doc The document.
+      #
+      # @since 3.0.0
+      def prepare_remove(doc)
+        @selector ||= root.atomic_selector
+        @path ||= doc.atomic_path
+        documents.delete_one(doc)
+        doc._parent.remove_child(doc)
+        doc.destroyed = true
+      end
+    end
+  end
+end

data/lib/mongoid/contextual/mongo.rb

@@ -0,0 +1,676 @@
+# encoding: utf-8
+require "mongoid/contextual/atomic"
+require "mongoid/contextual/aggregable/mongo"
+require "mongoid/contextual/command"
+require "mongoid/contextual/eager"
+require "mongoid/contextual/find_and_modify"
+require "mongoid/contextual/geo_near"
+require "mongoid/contextual/map_reduce"
+require "mongoid/contextual/text_search"
+
+module Mongoid
+  module Contextual
+    class Mongo
+      include Enumerable
+      include Aggregable::Mongo
+      include Atomic
+      include Eager
+      include Queryable
+
+      # @attribute [r] query The Moped query.
+      attr_reader :query
+
+      # Is the context cached?
+      #
+      # @example Is the context cached?
+      #   context.cached?
+      #
+      # @return [ true, false ] If the context is cached.
+      #
+      # @since 3.0.0
+      def cached?
+        !!@cache
+      end
+
+      # Get the number of documents matching the query.
+      #
+      # @example Get the number of matching documents.
+      #   context.count
+      #
+      # @example Get the count of documents matching the provided.
+      #   context.count(document)
+      #
+      # @example Get the count for where the provided block is true.
+      #   context.count do |doc|
+      #     doc.likes > 1
+      #   end
+      #
+      # @param [ Document ] document A document to match or true if wanting
+      #   skip and limit to be factored into the count.
+      #
+      # @return [ Integer ] The number of matches.
+      #
+      # @since 3.0.0
+      def count(document = false, &block)
+        return super(&block) if block_given?
+        if document.is_a?(Document)
+          return collection.find(criteria.and(_id: document.id).selector).count
+        end
+        return query.count(document) if document
+        try_cache(:count) { query.count }
+      end
+
+      # Delete all documents in the database that match the selector.
+      #
+      # @example Delete all the documents.
+      #   context.delete
+      #
+      # @return [ nil ] Nil.
+      #
+      # @since 3.0.0
+      def delete
+        self.count.tap do
+          query.remove_all
+        end
+      end
+      alias :delete_all :delete
+
+      # Destroy all documents in the database that match the selector.
+      #
+      # @example Destroy all the documents.
+      #   context.destroy
+      #
+      # @return [ nil ] Nil.
+      #
+      # @since 3.0.0
+      def destroy
+        destroyed = self.count
+        each do |doc|
+          doc.destroy
+        end
+        destroyed
+      end
+      alias :destroy_all :destroy
+
+      # Get the distinct values in the db for the provided field.
+      #
+      # @example Get the distinct values.
+      #   context.distinct(:name)
+      #
+      # @param [ String, Symbol ] field The name of the field.
+      #
+      # @return [ Array<Object> ] The distinct values for the field.
+      #
+      # @since 3.0.0
+      def distinct(field)
+        query.distinct(klass.database_field_name(field))
+      end
+
+      # Iterate over the context. If provided a block, yield to a Mongoid
+      # document for each, otherwise return an enum.
+      #
+      # @example Iterate over the context.
+      #   context.each do |doc|
+      #     puts doc.name
+      #   end
+      #
+      # @return [ Enumerator ] The enumerator.
+      #
+      # @since 3.0.0
+      def each(&block)
+        if block_given?
+          selecting do
+            documents_for_iteration.each do |doc|
+              yield_document(doc, &block)
+            end
+            @cache_loaded = true
+            eager_loadable? ? docs : self
+          end
+        else
+          to_enum
+        end
+      end
+
+      # Do any documents exist for the context.
+      #
+      # @example Do any documents exist for the context.
+      #   context.exists?
+      #
+      # @note We don't use count here since Mongo does not use counted
+      #   b-tree indexes, unless a count is already cached then that is
+      #   used to determine the value.
+      #
+      # @return [ true, false ] If the count is more than zero.
+      #
+      # @since 3.0.0
+      def exists?
+        return !documents.empty? if cached? && cache_loaded?
+        return @count > 0 if instance_variable_defined?(:@count)
+
+        try_cache(:exists) do
+          !!(query.dup.select(_id: 1).limit(1).first)
+        end
+      end
+
+      # Run an explain on the criteria.
+      #
+      # @example Explain the criteria.
+      #   Band.where(name: "Depeche Mode").explain
+      #
+      # @return [ Hash ] The explain result.
+      #
+      # @since 3.0.0
+      def explain
+        query.explain
+      end
+
+      # Execute the find and modify command, used for MongoDB's
+      # $findAndModify.
+      #
+      # @example Execute the command.
+      #   context.find_and_modify({ "$inc" => { likes: 1 }}, new: true)
+      #
+      # @param [ Hash ] update The updates.
+      # @param [ Hash ] options The command options.
+      #
+      # @option options [ true, false ] :new Return the updated document.
+      # @option options [ true, false ] :remove Delete the first document.
+      # @option options [ true, false ] :upsert Create the document if it doesn't exist.
+      #
+      # @return [ Document ] The result of the command.
+      #
+      # @since 3.0.0
+      def find_and_modify(update, options = {})
+        if doc = FindAndModify.new(collection, criteria, update, options).result
+          Factory.from_db(klass, doc)
+        end
+      end
+
+      # Get the first document in the database for the criteria's selector.
+      #
+      # @example Get the first document.
+      #   context.first
+      #
+      # @return [ Document ] The first document.
+      #
+      # @since 3.0.0
+      def first
+        return documents.first if cached? && cache_loaded?
+        try_cache(:first) do
+          with_sorting do
+            with_eager_loading(query.first)
+          end
+        end
+      end
+      alias :one :first
+
+      # Execute a $geoNear command against the database.
+      #
+      # @example Find documents close to 10, 10.
+      #   context.geo_near([ 10, 10 ])
+      #
+      # @example Find with spherical distance.
+      #   context.geo_near([ 10, 10 ]).spherical
+      #
+      # @example Find with a max distance.
+      #   context.geo_near([ 10, 10 ]).max_distance(0.5)
+      #
+      # @example Provide a distance multiplier.
+      #   context.geo_near([ 10, 10 ]).distance_multiplier(1133)
+      #
+      # @param [ Array<Float> ] coordinates The coordinates.
+      #
+      # @return [ GeoNear ] The GeoNear command.
+      #
+      # @since 3.1.0
+      def geo_near(coordinates)
+        GeoNear.new(collection, criteria, coordinates)
+      end
+
+      # Invoke the block for each element of Contextual. Create a new array
+      # containing the values returned by the block.
+      #
+      # If the symbol field name is passed instead of the block, additional
+      # optimizations would be used.
+      #
+      # @example Map by some field.
+      #   context.map(:field1)
+      #
+      # @exmaple Map with block.
+      #   context.map(&:field1)
+      #
+      # @param [ Symbol ] field The field name.
+      #
+      # @return [ Array ] The result of mapping.
+      def map(field = nil, &block)
+        if block_given?
+          super(&block)
+        else
+          field = field.to_sym
+          criteria.only(field).map(&field.to_proc)
+        end
+      end
+
+      # Create the new Mongo context. This delegates operations to the
+      # underlying driver - in Mongoid's case Moped.
+      #
+      # @example Create the new context.
+      #   Mongo.new(criteria)
+      #
+      # @param [ Criteria ] criteria The criteria.
+      #
+      # @since 3.0.0
+      def initialize(criteria)
+        @criteria, @klass, @cache = criteria, criteria.klass, criteria.options[:cache]
+        @collection = @klass.with(criteria.persistence_options || {}).collection
+        criteria.send(:merge_type_selection)
+        @query = collection.find(criteria.selector)
+        apply_options
+      end
+
+      delegate(:database_field_name, to: :@klass)
+
+      # Get the last document in the database for the criteria's selector.
+      #
+      # @example Get the last document.
+      #   context.last
+      #
+      # @return [ Document ] The last document.
+      #
+      # @since 3.0.0
+      def last
+        try_cache(:last) do
+          with_inverse_sorting do
+            with_eager_loading(query.first)
+          end
+        end
+      end
+
+      # Get's the number of documents matching the query selector.
+      #
+      # @example Get the length.
+      #   context.length
+      #
+      # @return [ Integer ] The number of documents.
+      #
+      # @since 3.0.0
+      def length
+        @length ||= self.count
+      end
+      alias :size :length
+
+      # Limits the number of documents that are returned from the database.
+      #
+      # @example Limit the documents.
+      #   context.limit(20)
+      #
+      # @param [ Integer ] value The number of documents to return.
+      #
+      # @return [ Mongo ] The context.
+      #
+      # @since 3.0.0
+      def limit(value)
+        query.limit(value) and self
+      end
+
+      # Initiate a map/reduce operation from the context.
+      #
+      # @example Initiate a map/reduce.
+      #   context.map_reduce(map, reduce)
+      #
+      # @param [ String ] map The map js function.
+      # @param [ String ] reduce The reduce js function.
+      #
+      # @return [ MapReduce ] The map/reduce lazy wrapper.
+      #
+      # @since 3.0.0
+      def map_reduce(map, reduce)
+        MapReduce.new(collection, criteria, map, reduce)
+      end
+
+      # Pluck the single field values from the database. Will return duplicates
+      # if they exist and only works for top level fields.
+      #
+      # @example Pluck a field.
+      #   context.pluck(:_id)
+      #
+      # @note This method will return the raw db values - it performs no custom
+      #   serialization.
+      #
+      # @param [ String, Symbol, Array ] field Fields to pluck.
+      #
+      # @return [ Array<Object, Array> ] The plucked values.
+      #
+      # @since 3.1.0
+      def pluck(*fields)
+        normalized_select = fields.inject({}) do |hash, f|
+          hash[klass.database_field_name(f)] = 1
+          hash
+        end
+
+        query.dup.select(normalized_select).map do |doc|
+          if normalized_select.size == 1
+            doc[normalized_select.keys.first]
+          else
+            normalized_select.keys.map { |n| doc[n] }.compact
+          end
+        end.compact
+      end
+
+      # Skips the provided number of documents.
+      #
+      # @example Skip the documents.
+      #   context.skip(20)
+      #
+      # @param [ Integer ] value The number of documents to skip.
+      #
+      # @return [ Mongo ] The context.
+      #
+      # @since 3.0.0
+      def skip(value)
+        query.skip(value) and self
+      end
+
+      # Sorts the documents by the provided spec.
+      #
+      # @example Sort the documents.
+      #   context.sort(name: -1, title: 1)
+      #
+      # @param [ Hash ] values The sorting values as field/direction(1/-1)
+      #   pairs.
+      #
+      # @return [ Mongo ] The context.
+      #
+      # @since 3.0.0
+      def sort(values = nil, &block)
+        if block_given?
+          super(&block)
+        else
+          # update the criteria
+          @criteria = criteria.order_by(values)
+          apply_option(:sort)
+          self
+        end
+      end
+
+      # Execute a text command against the database.
+      #
+      # @example Find documents with the text "phase"
+      #   context.text_search("phase")
+      #
+      # @param [ String ] query The text search query.
+      #
+      # @return [ TextSearch ] The TextSearch command.
+      #
+      # @since 4.0.0
+      def text_search(query)
+        TextSearch.new(collection, criteria, query)
+      end
+
+      # Update the first matching document atomically.
+      #
+      # @example Update the first matching document.
+      #   context.update({ "$set" => { name: "Smiths" }})
+      #
+      # @param [ Hash ] attributes The new attributes for the document.
+      #
+      # @return [ nil, false ] False if no attributes were provided.
+      #
+      # @since 3.0.0
+      def update(attributes = nil)
+        update_documents(attributes)
+      end
+
+      # Update all the matching documents atomically.
+      #
+      # @example Update all the matching documents.
+      #   context.update({ "$set" => { name: "Smiths" }})
+      #
+      # @param [ Hash ] attributes The new attributes for each document.
+      #
+      # @return [ nil, false ] False if no attributes were provided.
+      #
+      # @since 3.0.0
+      def update_all(attributes = nil)
+        update_documents(attributes, :update_all)
+      end
+
+      private
+
+      # yield the block given or return the cached value
+      #
+      # @param [ String, Symbol ] key The instance variable name
+      #
+      # @return the result of the block
+      #
+      # @since 3.1.4
+      def try_cache(key, &block)
+        unless cached?
+          yield
+        else
+          unless ret = instance_variable_get("@#{key}")
+            instance_variable_set("@#{key}", ret = yield)
+          end
+          ret
+        end
+      end
+
+      # Update the documents for the provided method.
+      #
+      # @api private
+      #
+      # @example Update the documents.
+      #   context.update_documents(attrs)
+      #
+      # @param [ Hash ] attributes The updates.
+      # @param [ Symbol ] method The method to use.
+      #
+      # @return [ true, false ] If the update succeeded.
+      #
+      # @since 3.0.4
+      def update_documents(attributes, method = :update)
+        return false unless attributes
+        attributes = Hash[attributes.map { |k, v| [klass.database_field_name(k.to_s), v] }]
+        query.send(method, attributes.__consolidate__(klass))
+      end
+
+      # Apply the field limitations.
+      #
+      # @api private
+      #
+      # @example Apply the field limitations.
+      #   context.apply_fields
+      #
+      # @since 3.0.0
+      def apply_fields
+        if spec = criteria.options[:fields]
+          query.select(spec)
+        end
+      end
+
+      # Apply the options.
+      #
+      # @api private
+      #
+      # @example Apply all options.
+      #   context.apply_options
+      #
+      # @since 3.1.0
+      def apply_options
+        apply_fields
+        [ :hint, :limit, :skip, :sort, :batch_size, :max_scan ].each do |name|
+          apply_option(name)
+        end
+        if criteria.options[:timeout] == false
+          query.no_timeout
+        end
+      end
+
+      # Apply an option.
+      #
+      # @api private
+      #
+      # @example Apply the skip option.
+      #   context.apply_option(:skip)
+      #
+      # @since 3.1.0
+      def apply_option(name)
+        if spec = criteria.options[name]
+          query.send(name, spec)
+        end
+      end
+
+      # Apply an ascending id sort for use with #first queries, only if no
+      # other sorting is provided.
+      #
+      # @api private
+      #
+      # @example Apply the id sorting params to the given block
+      #   context.with_sorting
+      #
+      # @since 3.0.0
+      def with_sorting
+        begin
+          unless criteria.options.has_key?(:sort)
+            query.sort(_id: 1)
+          end
+          yield
+        ensure
+          apply_option(:sort)
+        end
+      end
+
+      # Map the inverse sort symbols to the correct MongoDB values.
+      #
+      #  @api private
+      #
+      # @example Apply the inverse sorting params to the given block
+      #   context.with_inverse_sorting
+      #
+      # @since 3.0.0
+      def with_inverse_sorting
+        begin
+          if spec = criteria.options[:sort]
+            query.sort(Hash[spec.map{|k, v| [k, -1*v]}])
+          else
+            query.sort(_id: -1)
+          end
+          yield
+        ensure
+          apply_option(:sort)
+        end
+      end
+
+      # Is the cache able to be added to?
+      #
+      # @api private
+      #
+      # @example Is the context cacheable?
+      #   context.cacheable?
+      #
+      # @return [ true, false ] If caching, and the cache isn't loaded.
+      #
+      # @since 3.0.0
+      def cacheable?
+        cached? && !cache_loaded?
+      end
+
+      # Is the cache fully loaded? Will be true if caching after one full
+      # iteration.
+      #
+      # @api private
+      #
+      # @example Is the cache loaded?
+      #   context.cache_loaded?
+      #
+      # @return [ true, false ] If the cache is loaded.
+      #
+      # @since 3.0.0
+      def cache_loaded?
+        !!@cache_loaded
+      end
+
+      # Get the documents for cached queries.
+      #
+      # @api private
+      #
+      # @example Get the cached documents.
+      #   context.documents
+      #
+      # @return [ Array<Document> ] The documents.
+      #
+      # @since 3.0.0
+      def documents
+        @documents ||= []
+      end
+
+      # Get the documents the context should iterate. This follows 3 rules:
+      #
+      # 1. If the query is cached, and we already have documents loaded, use
+      #   them.
+      # 2. If we are eager loading, then eager load the documents and use
+      #   those.
+      # 3. Use the query.
+      #
+      # @api private
+      #
+      # @example Get the documents for iteration.
+      #   context.documents_for_iteration
+      #
+      # @return [ Array<Document>, Moped::Query ] The docs to iterate.
+      #
+      # @since 3.0.0
+      def documents_for_iteration
+        if cached? && !documents.empty?
+          documents
+        elsif eager_loadable?
+          docs = query.map{ |doc| Factory.from_db(klass, doc) }
+          eager_load(docs)
+          docs
+        else
+          query
+        end
+      end
+
+      # If we are limiting results, we need to set the field limitations on a
+      # thread local to avoid overriding the default values.
+      #
+      # @example Execute with selection.
+      #   context.selecting do
+      #     collection.find
+      #   end
+      #
+      # @return [ Object ] The yielded value.
+      #
+      # @since 2.4.4
+      def selecting
+        begin
+          fields = criteria.options[:fields]
+          Threaded.set_selection(criteria.object_id, fields) unless fields.blank?
+          yield
+        ensure
+          Threaded.delete_selection(criteria.object_id)
+        end
+      end
+
+      # Yield to the document.
+      #
+      # @api private
+      #
+      # @example Yield the document.
+      #   context.yield_document(doc) do |doc|
+      #     ...
+      #   end
+      #
+      # @param [ Document ] document The document to yield to.
+      #
+      # @since 3.0.0
+      def yield_document(document, &block)
+        doc = document.respond_to?(:_id) ?
+          document : Factory.from_db(klass, document, criteria.object_id)
+        yield(doc)
+        documents.push(doc) if cacheable?
+      end
+    end
+  end
+end