Pull out yield and increment functionality

lib/mongoid/contextual/mongo.rb

@@ -33,6 +33,18 @@ def blank?
       end
       alias :empty? :blank?
 
+      # 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.
@@ -114,22 +126,20 @@ def distinct(field)
       # @return [ Enumerator ] The enumerator.
       #
       # @since 3.0.0
-      def each
+      def each(&block)
         if block_given?
           reset_length
           selecting do
             if eager_loadable?
               docs = query.map{ |doc| Factory.from_db(klass, doc) }
               eager_load(docs)
               docs.each do |doc|
-                yield doc
-                increment_length
+                yield_and_increment(doc, &block)
               end
               docs
             else
               query.each do |doc|
-                yield Factory.from_db(klass, doc)
-                increment_length
+                yield_and_increment(Factory.from_db(klass, doc), &block)
               end
               self
             end
@@ -139,6 +149,23 @@ def each
         end
       end
 
+      # Yield to the document and increment the length.
+      #
+      # @api private
+      #
+      # @example Yield and increment.
+      #   context.yield_and_increment(doc) do |doc|
+      #     ...
+      #   end
+      #
+      # @param [ Document ] doc The document to yield to.
+      #
+      # @since 3.0.0
+      def yield_and_increment(doc, &block)
+        yield(doc)
+        increment_length
+      end
+
       # Do any documents exist for the context.
       #
       # @example Do any documents exist for the context.
@@ -208,7 +235,7 @@ def first
       #
       # @since 3.0.0
       def initialize(criteria)
-        @criteria, @klass = criteria, criteria.klass
+        @criteria, @klass, @cache = criteria, criteria.klass, criteria.options[:cache]
         add_type_selection
         @query = klass.collection.find(criteria.selector)
         apply_options

spec/mongoid/contextual/mongo_spec.rb

@@ -42,6 +42,39 @@
     end
   end
 
+  describe "#cached?" do
+
+    context "when the criteria is cached" do
+
+      let(:criteria) do
+        Band.all.cache
+      end
+
+      let(:context) do
+        described_class.new(criteria)
+      end
+
+      it "returns true" do
+        context.should be_cached
+      end
+    end
+
+    context "when the criteria is not cached" do
+
+      let(:criteria) do
+        Band.all
+      end
+
+      let(:context) do
+        described_class.new(criteria)
+      end
+
+      it "returns false" do
+        context.should_not be_cached
+      end
+    end
+  end
+
   describe "#count" do
 
     let!(:depeche) do

spec/mongoid/criteria_spec.rb

@@ -271,6 +271,28 @@
     end
   end
 
+  describe "#cache" do
+
+    let!(:band) do
+      Band.create(name: "Front 242")
+    end
+
+    let(:criteria) do
+      Band.where(name: "Front 242").cache
+    end
+
+    before do
+      Moped.logger.level = Logger::DEBUG
+      criteria.each {}
+    end
+
+    pending "only hits the database once" do
+      criteria.each do |doc|
+        doc.should eq(band)
+      end
+    end
+  end
+
   [ :clone, :dup ].each do |method|
 
     describe "\##{method}" do