protobuf-activerecord 3.4.4 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b94b8ba65793cc1162ee6905716c95d8ba2afb16
-  data.tar.gz: 02fd2e40603b22fc90c9f44f81d724c9940f5054
+  metadata.gz: 6ebddfb7f1a2b6a894d213d63cec1a179e69c88c
+  data.tar.gz: 2ddf9cc3994a46fb2ec4c3118121be657faf7e2a
 SHA512:
-  metadata.gz: 1c2ceafcbbfe007d619a96fb3289443fa1dfbffef453e139359618d36e4b845a575cefad8bfe248ef3b9ab8aacfe9233325a727941a60cb0cd7ab1176c15bcf7
-  data.tar.gz: 678912754b8c1a7ec44a7d69c9232d4971bd6d225526a098e795a9a864a494c9b36a29badf1b4cb3217df56039bb5f02653c298c40e92d2339ba6575cb2b2d3b
+  metadata.gz: 4a5386b5374b38a42c3b507ff848c2afef0bea3d93ac3e8435e6c9863c87ff6fe1ef6bdf2c3d9ff7de7931b9735d92e0b673e268744140b28e23a733d7617ff9
+  data.tar.gz: f17ccbe9174babd312ebb75d35ffb65f8aff1c31886e20420d5f314029a3febf258eb377bc995b12e7cdf9e9256286938994d63bf801b0b83676d1b666581b45

data/README.md

@@ -255,6 +255,53 @@ User.limit(10).search_scope(request)
 
 Protobuf Active Record also provides some aliases for the `search_scope` method in the event that you'd like something a little more descriptive: `by_fields` and `scope_from_proto` are all aliases of `search_scope`.
 
+#### Upsert
+
+Protobuf Active Record provides the ability to create a new record, or update an existing record if an existing record is found. This is implemented using Active Record's `first_or_initialize` method.
+
+```Ruby
+class User < ActiveRecord::Base
+  scope :by_guid, lambda { |*values| where(:guid => values) }
+  scope :by_first_name, lambda { |*values| where(:first_name => values) }
+  scope :by_last_name, lambda { |*values| where(:last_name => values) }
+
+  field_scope :guid
+  field_scope :first_name
+  field_scope :last_name
+
+  upsert_key :guid
+  upsert_key :first_name, :last_name
+end
+
+@user = User.for_upsert(request)
+```
+
+Note: An upsert_key should only be defined on a field or set of fields that have a unique constraint
+
+Note: All fields used in an upsert key must also have a field_scope defined
+
+If multiple upsert_keys match the request, the first matching upsert key will be used, in order of declaration. In the typical use-case where upsert keys have corresponding unique constraints the results should be equivalent regardless of order.
+
+Protobuf Active Record provides several methods for invoking an upsert.
+
+The first approach is to use the `for_upsert` method to look up a record.
+
+```Ruby
+  @user = User.for_upsert(proto)
+```
+
+Alternatively, you can use `upsert` to look up the record and perform the persistence in the same call.
+
+```Ruby
+  # Example
+  User.upsert(proto)
+
+  # This is equivalent to
+  user = User.for_upsert(proto)
+  user.assign_attributes(proto)
+  user.save
+```
+
 ## Contributing
 
 1. Fork it

data/lib/protobuf/active_record/errors.rb

@@ -38,5 +38,13 @@ module Protobuf
     # Raised by `field_scope` when given scope is not defined.
     class SearchScopeError < ProtobufActiveRecordError
     end
+
+    # Raised by `upsert_scope` when a given scope is not defined
+    class UpsertScopeError < ProtobufActiveRecordError
+    end
+
+    # Raised by `for_upsert` when no valid upsert_scopes are found
+    class UpsertNotFoundError < ProtobufActiveRecordError
+    end
   end
 end

data/lib/protobuf/active_record/scope.rb

@@ -111,6 +111,80 @@ module Protobuf
         def searchable_field_parsers
           @_searchable_field_parsers ||= {}
         end
+
+        # Defines a scope that is eligible for upsert. The scope will be
+        # used to initialize a record with first_or_initialize. An upsert scope
+        # declariation must specify one or more fields that are required to
+        # be present on the request and also must have a field_scope defined.
+        #
+        # If multiple upsert scopes are specified, they will be searched in
+        # the order they are declared for the first valid scope.
+        #
+        # Examples:
+        #
+        #   class User < ActiveRecord::Base
+        #     scope :by_guid, lambda { |*guids| where(:guid => guids) }
+        #     scope :by_external_guid, lambda { |*external_guids|
+        #       where(:external_guid => exteranl_guids)
+        #     }
+        #     scope :by_client_guid, lambda { |*client_guids|
+        #       joins(:client).where(
+        #         :clients => { :guid => client_guids }
+        #        )
+        #     }
+        #
+        #     field_scope :guid
+        #     field_scope :client_guid
+        #     field_scope :external_guid
+        #
+        #     upsert_scope :external_guid, :client_guid
+        #     upsert_scope :guid
+        #
+        #   end
+        #
+        def upsert_key(*fields)
+          fields = fields.flatten
+
+          fields.each do |field|
+            fail UpsertScopeError unless searchable_fields[field].present?
+          end
+
+          upsert_keys << fields
+        end
+
+        def upsert_keys
+          @_upsert_keys ||= []
+        end
+
+        def for_upsert(proto)
+          valid_upsert = upsert_keys.find do |upsert_key|
+            upsert_key.all? do |field|
+              proto.respond_to_and_has_and_present?(field)
+            end
+          end
+
+          fail UpsertNotFoundError unless valid_upsert.present?
+
+          upsert_scope = model_scope
+          valid_upsert.each do |field|
+            value = proto.__send__(field)
+            upsert_scope = upsert_scope.__send__(searchable_fields[field], value)
+          end
+
+          upsert_scope.first_or_initialize
+        end
+
+        def upsert(proto)
+          record = for_upsert(proto)
+          record.assign_attributes(proto)
+          record.save
+        end
+
+        def upsert!(proto)
+          record = for_upsert(proto)
+          record.assign_attributes(proto)
+          record.save!
+        end
       end
     end
   end

data/lib/protobuf/active_record/version.rb

@@ -1,5 +1,5 @@
 module Protobuf
   module ActiveRecord
-    VERSION = "3.4.4"
+    VERSION = "3.5.0"
   end
 end

data/spec/protobuf/active_record/scope_spec.rb

@@ -9,6 +9,7 @@ describe Protobuf::ActiveRecord::Scope do
   after do
     User.instance_variable_set("@_searchable_field_parsers", @field_parsers)
     User.instance_variable_set("@_searchable_fields", @fields)
+    User.instance_variable_set("@_upsert_keys", [])
   end
 
 
@@ -78,7 +79,6 @@ describe Protobuf::ActiveRecord::Scope do
   end
 
   describe ".parse_search_values" do
-
     it "converts single values to collections" do
       proto = UserMessage.new(:email => "the.email@test.in")
 
@@ -116,4 +116,87 @@ describe Protobuf::ActiveRecord::Scope do
       end
     end
   end
+
+  describe ".upsert_key" do
+    it "adds the fields to the upsert_keys" do
+      ::User.field_scope(:guid)
+      ::User.upsert_key(:guid)
+      expect(::User.upsert_keys).to eq([[:guid]])
+    end
+
+    context "no field_scope defined" do
+      it "raises an error" do
+        expect { ::User.upsert_key(:foobar) }.to raise_error(::Protobuf::ActiveRecord::UpsertScopeError)
+      end
+    end
+  end
+
+  describe ".for_upsert" do
+    let(:guid) { "USR-1" }
+    let(:proto) { ::UserMessage.new(:guid => guid) }
+
+    before do
+      ::User.delete_all
+      ::User.field_scope(:guid)
+      ::User.upsert_key(:guid)
+    end
+
+    context "no matching upsert keys" do
+      let(:proto) { ::UserMessage.new }
+
+      it "raises an error" do
+        expect { ::User.for_upsert(proto) }.to raise_error(::Protobuf::ActiveRecord::UpsertNotFoundError)
+      end
+    end
+
+    context "no existing records" do
+      it "returns a new record" do
+        record = ::User.for_upsert(proto)
+        expect(record.new_record?).to be true
+      end
+    end
+
+    context "existing record" do
+      before { ::User.create(:guid => guid) }
+      after { ::User.delete_all }
+
+      it "returns the existing record" do
+        record = ::User.for_upsert(proto)
+        expect(record.new_record?).to be false
+      end
+    end
+  end
+
+  describe ".upsert" do
+    let(:guid) { "USR-1" }
+    let(:proto) { ::UserMessage.new(:guid => guid, :email => "bar") }
+
+    before do
+      ::User.delete_all
+      ::User.field_scope(:guid)
+      ::User.upsert_key(:guid)
+    end
+
+    context "no existing records" do
+      it "creates a new record" do
+        ::User.upsert(proto)
+        expect(::User.count).to eq(1)
+      end
+    end
+
+    context "existing record" do
+      before { ::User.create(:guid => guid, :email => "foo") }
+      after { ::User.delete_all }
+
+      it "updates the existing record" do
+        ::User.upsert(proto)
+        expect(::User.first.email).to eq("bar")
+      end
+
+      it "returns true when valid" do
+        result = ::User.upsert(proto)
+        expect(result).to be true
+      end
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: protobuf-activerecord
 version: !ruby/object:Gem::Version
-  version: 3.4.4
+  version: 3.5.0
 platform: ruby
 authors:
 - Adam Hutchison
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-09-27 00:00:00.000000000 Z
+date: 2018-01-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -250,7 +250,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.6.13
+rubygems_version: 2.6.10
 signing_key: 
 specification_version: 4
 summary: Google Protocol Buffers integration for Active Record