Adding Criteria#first

lib/mongoid/criteria.rb

@@ -341,6 +341,8 @@ def one
       attributes ? @klass.instantiate(attributes) : nil
     end
 
+    alias :first :one
+
     # Adds a criterion to the +Criteria+ that specifies the fields that will
     # get returned from the Document. Used mainly for list views that do not
     # require all fields to be present. This is similar to SQL "SELECT" values.

spec/unit/mongoid/criteria_spec.rb

@@ -239,7 +239,37 @@
 
   end
 
-  describe "#each_index" do
+  describe "#first" do
+
+    context "when documents exist" do
+
+      before do
+        @collection = mock
+        Person.expects(:collection).returns(@collection)
+        @collection.expects(:find_one).with(@criteria.selector, @criteria.options).returns({ :title => "Sir" })
+      end
+
+      it "calls find on the collection with the selector and options" do
+        criteria = Mongoid::Criteria.new(Person)
+        criteria.first.should be_a_kind_of(Person)
+      end
+
+    end
+
+    context "when no documents exist" do
+
+      before do
+        @collection = mock
+        Person.expects(:collection).returns(@collection)
+        @collection.expects(:find_one).with(@criteria.selector, @criteria.options).returns(nil)
+      end
+
+      it "returns nil" do
+        criteria = Mongoid::Criteria.new(Person)
+        criteria.first.should be_nil
+      end
+
+    end
 
   end