Added Collection#first_or_new and Collection#first_or_create

lib/dm-core/collection.rb

@@ -616,6 +616,38 @@ def build(*args)
       new(*args)
     end
 
+    ##
+    # Finds the first Resource by conditions, or initializes a new
+    # Resource with the attributes if none found
+    #
+    # @param [Hash] conditions
+    #   The conditions to be used to search
+    # @param [Hash] attributes
+    #   The attributes to be used to create the record of none is found.
+    # @return [DataMapper::Resource]
+    #   The instance found by +query+, or created with +attributes+ if none found
+    #
+    # @api public
+    def first_or_new(conditions, attributes = {})
+      first(conditions) || new(conditions.merge(attributes))
+    end
+
+    ##
+    # Finds the first Resource by conditions, or creates a new
+    # Resource with the attributes if none found
+    #
+    # @param [Hash] conditions
+    #   The conditions to be used to search
+    # @param [Hash] attributes
+    #   The attributes to be used to create the record of none is found.
+    # @return [DataMapper::Resource]
+    #   The instance found by +query+, or created with +attributes+ if none found
+    #
+    # @api public
+    def first_or_create(conditions, attributes = {})
+      first(conditions) || create(conditions.merge(attributes))
+    end
+
     ##
     # Initializes a Resource and appends it to the Collection
     #

lib/dm-core/model.rb

@@ -335,21 +335,35 @@ def first(*args)
     # TODO: add #last
 
     ##
-    # Finds the #first record by a query, or #create one by attributes
-    # if none was found
+    # Finds the first Resource by conditions, or initializes a new
+    # Resource with the attributes if none found
     #
-    # @param [Hash] query
-    #   The query to be used so search
+    # @param [Hash] conditions
+    #   The conditions to be used to search
+    # @param [Hash] attributes
+    #   The attributes to be used to create the record of none is found.
+    # @return [DataMapper::Resource]
+    #   The instance found by +query+, or created with +attributes+ if none found
+    #
+    # @api public
+    def first_or_new(conditions, attributes = {})
+      first(conditions) || new(conditions.merge(attributes))
+    end
+
+    ##
+    # Finds the first Resource by conditions, or creates a new
+    # Resource with the attributes if none found
+    #
+    # @param [Hash] conditions
+    #   The conditions to be used to search
     # @param [Hash] attributes
     #   The attributes to be used to create the record of none is found.
     # @return [DataMapper::Resource]
     #   The instance found by +query+, or created with +attributes+ if none found
-    # @see #first
-    # @see #create
     #
     # @api public
-    def first_or_create(query, attributes = {})
-      first(query) || create(query.merge(attributes))
+    def first_or_create(conditions, attributes = {})
+      first(conditions) || create(conditions.merge(attributes))
     end
 
     ##

spec/public/shared/collection_shared_spec.rb

@@ -732,9 +732,104 @@
     end
   end
 
-  it 'should respond to #first_or_create' do
-    pending 'TODO: add Collection#first_or_create'
-    @articles.should respond_to(:first_or_create)
+  it { @articles.should respond_to(:first_or_create) }
+
+  describe '#first_or_create' do
+    describe 'with conditions that find an existing Resource' do
+      before do
+        @return = @resource = @articles.first_or_create(@article.attributes)
+      end
+
+      it 'should return a Resource' do
+        @return.should be_kind_of(DataMapper::Resource)
+      end
+
+      it 'should be expected Resource' do
+        @resource.should == @article
+      end
+
+      it 'should be a saved Resource' do
+        @resource.should_not be_new_record
+      end
+
+      it 'should relate the Resource to the Collection' do
+        @resource.collection.should be_equal(@articles)
+      end
+    end
+
+    describe 'with conditions that do not find an existing Resource' do
+      before do
+        @conditions = { :content => 'Unknown Content' }
+        @attributes = {}
+        @return = @resource = @articles.first_or_create(@conditions, @attributes)
+      end
+
+      it 'should return a Resource' do
+        @return.should be_kind_of(DataMapper::Resource)
+      end
+
+      it 'should be expected Resource' do
+        @resource.attributes.only(:title, :content).should == { :title => 'Sample Article', :content => 'Unknown Content' }
+      end
+
+      it 'should be a saved Resource' do
+        @resource.should_not be_new_record
+      end
+
+      it 'should relate the Resource to the Collection' do
+        @resource.collection.should be_equal(@articles)
+      end
+    end
+  end
+
+  it { @articles.should respond_to(:first_or_new) }
+
+  describe '#first_or_new' do
+    describe 'with conditions that find an existing Resource' do
+      before do
+        @return = @resource = @articles.first_or_new(@article.attributes)
+      end
+
+      it 'should return a Resource' do
+        @return.should be_kind_of(DataMapper::Resource)
+      end
+
+      it 'should be expected Resource' do
+        @resource.should == @article
+      end
+
+      it 'should be a saved Resource' do
+        @resource.should_not be_new_record
+      end
+
+      it 'should relate the Resource to the Collection' do
+        @resource.collection.should be_equal(@articles)
+      end
+    end
+
+    describe 'with conditions that do not find an existing Resource' do
+      before do
+        @conditions = { :content => 'Unknown Content' }
+        @attributes = {}
+        @return = @resource = @articles.first_or_new(@conditions, @attributes)
+      end
+
+      it 'should return a Resource' do
+        @return.should be_kind_of(DataMapper::Resource)
+      end
+
+      it 'should be expected Resource' do
+        @resource.attributes.only(:title, :content).should == { :title => 'Sample Article', :content => 'Unknown Content' }
+      end
+
+      it 'should not be a saved Resource' do
+        @resource.should be_new_record
+      end
+
+      it 'should relate the Resource to the Collection' do
+        @resource.collection.should be_equal(@articles)
+      end
+    end
   end
 
   it { @articles.should respond_to(:get) }

spec/public/transaction_spec.rb

@@ -1,7 +1,7 @@
 require File.expand_path(File.join(File.dirname(__FILE__), '..', 'spec_helper'))
 
 describe DataMapper::Resource, "Transactions" do
-  
+
   before do
     Object.send(:remove_const, :User) if defined?(User)
     class User
@@ -24,7 +24,7 @@ class Comment
       belongs_to :user
     end
   end
-  
+
   supported_by :postgres, :mysql do
     before(:each) do
       # --- Temporary private api use to get around rspec limitations ---
@@ -33,48 +33,48 @@ class Comment
         transaction.begin
         repository.adapter.push_transaction(transaction)
       end
-              
+
       @model       = User
       @child_model = Comment
       @user        = @model.create(:name => 'dbussink', :age => 25, :description => "Test")
     end
-    
+
     after do
       repository = repository(:default)
       while repository.adapter.current_transaction
         repository.adapter.current_transaction.rollback
         repository.adapter.pop_transaction
       end
     end
-      
+
     it_should_behave_like 'A public Resource'
-    
+
   end
-  
+
   supported_by :postgres, :mysql do
-  
+
     describe "#transaction" do
-          
+
       it "should have access to resources presisted before the transaction" do
         User.create(:name => "carllerche")
         User.transaction do
           User.first.name.should == "carllerche"
         end
       end
-      
+
       it "should have access to resources persisted in the transaction" do
         User.transaction do
           User.create(:name => "carllerche")
           User.first.name.should == "carllerche"
         end
       end
-      
+
       it "should not mark persisted resources as new records" do
         User.transaction do
           User.create(:name => "carllerche").should_not be_new_record
         end
       end
-      
+
       it "should rollback when an error is thrown in a transaction" do
         lambda {
           User.transaction do
@@ -84,9 +84,9 @@ class Comment
         }.should raise_error("I love coffee")
         User.first.should be_nil
       end
-      
+
     end
-    
+
   end
-  
+
 end