restforce-db 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8e6b77ef750532361625bbec55ad4a00e1ae4d21
-  data.tar.gz: b88d477b1e2a2ea7f2e301b35c54b08d77612bb4
+  metadata.gz: df2303b0a1b785e92719f690b7d5ea5f6ec9ad09
+  data.tar.gz: 1add9035c044ff8022562d547c1cab48c6c35299
 SHA512:
-  metadata.gz: 89a255caf32a25c81b24415bd5d7b389a19219e0055b7af73f3c59388a1b0914f8eb827dfe48752f528a46b65f766fb8ab9060261a6a116460b43575032da136
-  data.tar.gz: 53d5e840aeaee28b666979b7a97e31f85bebd7bcd6bb6d6611f125f3bc6ae7c995de187749680d19ee6fdb51c3b0728ec03ae6069aad68429201fca0d444fc4d
+  metadata.gz: e7de9ccdec2e054a494cb31d1caf00636e0893de35dd474aaa11862b42b2028be1fa8c50174a600594fa61e23284f7f0510946340c8f19f4bfbcb02d2a9a9c44
+  data.tar.gz: dbae2200380469cd1ef662a9b05f3324309f37e6ac0a6615bb41cedb94b7e99b68e080207728eccdb45c0ec3245f4c8093196ecee698bc9523a6714b768264fc

data/README.md

@@ -42,14 +42,31 @@ class Restaurant < ActiveRecord::Base
   has_one :chef, inverse_of: :restaurant
   has_many :dishes, inverse_of: :restaurant
 
+  module StyleAdapter
+
+    def self.to_salesforce(value)
+      "#{value} in Salesforce"
+    end
+
+    def self.to_database(value)
+      value.chomp(" in Salesforce")
+    end
+
+  end
+
   sync_with("Restaurant__c", :always) do
     where "StarRating__c > 4"
     has_many :dishes, through: "Restaurant__c"
     belongs_to :chef, through: %w(Chef__c Cuisine__c)
+
     maps(
       name:  "Name",
       style: "Style__c",
     )
+
+    converts(
+      style: StyleAdapter,
+    )
   end
 
 end
@@ -118,6 +135,10 @@ Individual conditions supplied to `where` will be appended together with `AND` c
 
 `maps` defines a set of direct field-to-field mappings. It takes a Hash as an argument; the keys should line up with your ActiveRecord attribute names, while the values should line up with the matching field names in Salesforce.
 
+#### Field Conversions
+
+`converts` defines a set of value adapters. It takes a Hash as an argument; the keys should line up with the ActiveRecord attribute names defined in your `maps` clause, while the values should be the corresponding adapter objects. The only requirement for an adapter is that it respond to the methods `#to_database` and `#to_salesforce`.
+
 #### Associations
 
 Associations in `Restforce::DB` can be a little tricky, as they depend on your ActiveRecord association mappings, but are independent of those mappings, and can even (as seen above) seem to conflict with them.

data/lib/restforce/db/attribute_map.rb

@@ -6,16 +6,38 @@ module Restforce
     # various representations of attribute hashes.
     class AttributeMap
 
+      # DefaultAdapter defines the default data conversions between database and
+      # Salesforce formats. It translates Dates and Times to ISO-8601 format for
+      # storage in Salesforce.
+      module DefaultAdapter
+
+        # :nodoc:
+        def self.to_database(value)
+          value
+        end
+
+        # :nodoc:
+        def self.to_salesforce(value)
+          value = value.respond_to?(:utc) ? value.utc : value
+          value.respond_to?(:iso8601) ? value.iso8601 : value
+        end
+
+      end
+
       # Public: Initialize a Restforce::DB::AttributeMap.
       #
       # database_model   - A Class compatible with ActiveRecord::Base.
       # salesforce_model - A String name of an object type in Salesforce.
       # fields           - A Hash of mappings between database columns and
       #                    fields in Salesforce.
-      def initialize(database_model, salesforce_model, fields = {})
+      # conversions      - A Hash of mappings between database columns and the
+      #                    corresponding adapter objects which should be used to
+      #                    convert between data formats.
+      def initialize(database_model, salesforce_model, fields = {}, conversions = {})
         @database_model = database_model
         @salesforce_model = salesforce_model
         @fields = fields
+        @conversions = conversions
 
         @types = {
           database_model   => :database,
@@ -33,19 +55,17 @@ module Restforce
       # Yields a series of attribute names.
       # Returns a Hash.
       def attributes(from_format)
-        use_mappings =
-          case @types[from_format]
-          when :salesforce
-            @fields
-          when :database
-            # Generate a mapping of database column names to record attributes.
-            @fields.keys.zip(@fields.keys)
-          else
-            raise ArgumentError
+        case @types[from_format]
+        when :salesforce
+          @fields.each_with_object({}) do |(attribute, mapping), values|
+            values[attribute] = adapter(attribute).to_database(yield(mapping))
           end
-
-        use_mappings.each_with_object({}) do |(attribute, mapping), values|
-          values[attribute] = yield(mapping)
+        when :database
+          @fields.keys.each_with_object({}) do |attribute, values|
+            values[attribute] = yield(attribute)
+          end
+        else
+          raise ArgumentError
         end
       end
 
@@ -79,10 +99,7 @@ module Restforce
         when :salesforce
           @fields.each_with_object({}) do |(attribute, mapping), converted|
             next unless attributes.key?(attribute)
-            value = attributes[attribute]
-            value = value.respond_to?(:utc) ? value.utc : value
-            value = value.respond_to?(:iso8601) ? value.iso8601 : value
-
+            value = adapter(attribute).to_salesforce(attributes[attribute])
             converted[mapping] = value
           end
         else
@@ -124,7 +141,8 @@ module Restforce
         when :database
           @fields.each_with_object({}) do |(attribute, mapping), converted|
             next unless attributes.key?(mapping)
-            converted[attribute] = attributes[mapping]
+            value = adapter(attribute).to_database(attributes[mapping])
+            converted[attribute] = value
           end
         when :salesforce
           attributes.dup
@@ -133,6 +151,15 @@ module Restforce
         end
       end
 
+      # Internal: Get the data format adapter for the passed attribute. Defaults
+      # to DefaultAdapter if no adapter has been explicitly assigned for the
+      # attribute.
+      #
+      # Returns an Object.
+      def adapter(attribute)
+        @conversions[attribute] || DefaultAdapter
+      end
+
     end
 
   end

data/lib/restforce/db/dsl.rb

@@ -85,6 +85,22 @@ module Restforce
         @mapping.fields = fields
       end
 
+      # Public: Define a set of adapters which should be used to translate data
+      # between the database and Salesforce.
+      #
+      # fields - A Hash, with keys corresponding to attributes of the database
+      #          record, and adapter objects as values.
+      #
+      # Raises ArgumentError if any adapter object has an incomplete interface.
+      # Returns nothing.
+      def converts(conversions)
+        unless conversions.values.all? { |c| c.respond_to?(:to_database) && c.respond_to?(:to_salesforce) }
+          raise ArgumentError, "All adapters must implement `to_database` and `to_salesforce` methods"
+        end
+
+        @mapping.conversions = conversions
+      end
+
     end
 
   end

data/lib/restforce/db/mapping.rb

@@ -26,6 +26,7 @@ module Restforce
 
       attr_accessor(
         :fields,
+        :conversions,
         :associations,
         :conditions,
         :strategy,
@@ -44,6 +45,7 @@ module Restforce
         @salesforce_record_type = RecordTypes::Salesforce.new(salesforce_model, self)
 
         self.fields = {}
+        self.conversions = {}
         self.associations = []
         self.conditions = []
         self.strategy = strategy
@@ -91,7 +93,7 @@ module Restforce
       #
       # Returns a Restforce::DB::AttributeMap.
       def attribute_map
-        @attribute_map ||= AttributeMap.new(database_model, salesforce_model, fields)
+        @attribute_map ||= AttributeMap.new(database_model, salesforce_model, fields, conversions)
       end
 
     end

data/lib/restforce/db/version.rb

@@ -3,7 +3,7 @@ module Restforce
   # :nodoc:
   module DB
 
-    VERSION = "1.1.0"
+    VERSION = "1.2.0"
 
   end
 

data/test/lib/restforce/db/attribute_map_test.rb

@@ -12,8 +12,8 @@ describe Restforce::DB::AttributeMap do
       column_two: "SF_Field_Two__c",
     }
   end
-
-  let(:attribute_map) { Restforce::DB::AttributeMap.new(database_model, salesforce_model, fields) }
+  let(:conversions) { {} }
+  let(:attribute_map) { Restforce::DB::AttributeMap.new(database_model, salesforce_model, fields, conversions) }
 
   describe "#attributes" do
     let(:mapping) do
@@ -41,6 +41,18 @@ describe Restforce::DB::AttributeMap do
       expect(attributes.keys).to_equal(mapping.database_fields)
       expect(attributes.values).to_equal(mapping.salesforce_fields)
     end
+
+    describe "when an adapter has been defined for an attribute" do
+      let(:conversions) { { column_one: boolean_adapter } }
+
+      it "uses the adapter to convert the value returned by the block" do
+        attributes = attribute_map.attributes(salesforce_model) { |_| "Yes" }
+        expect(attributes).to_equal(
+          column_one: true,
+          column_two: "Yes",
+        )
+      end
+    end
   end
 
   describe "#convert" do
@@ -66,6 +78,19 @@ describe Restforce::DB::AttributeMap do
         )
       end
     end
+
+    describe "when an adapter has been defined for an attribute" do
+      let(:conversions) { { column_one: boolean_adapter } }
+
+      it "uses the adapter to convert that attribute to a Salesforce-compatible form" do
+        expect(attribute_map.convert(salesforce_model, column_one: true)).to_equal(
+          "SF_Field_One__c" => "Yes",
+        )
+        expect(attribute_map.convert(salesforce_model, column_one: false)).to_equal(
+          "SF_Field_One__c" => "No",
+        )
+      end
+    end
   end
 
   describe "#convert_from_salesforce" do
@@ -80,6 +105,19 @@ describe Restforce::DB::AttributeMap do
     it "performs no special conversion for Salesforce fields" do
       expect(attribute_map.convert_from_salesforce(salesforce_model, attributes)).to_equal(attributes)
     end
+
+    describe "when an adapter has been defined for an attribute" do
+      let(:conversions) { { column_one: boolean_adapter } }
+
+      it "uses the adapter to convert that attribute to a database-compatible form" do
+        expect(attribute_map.convert_from_salesforce(database_model, "SF_Field_One__c" => "Yes")).to_equal(
+          column_one: true,
+        )
+        expect(attribute_map.convert_from_salesforce(database_model, "SF_Field_One__c" => "No")).to_equal(
+          column_one: false,
+        )
+      end
+    end
   end
 
 end

data/test/lib/restforce/db/dsl_test.rb

@@ -96,4 +96,22 @@ describe Restforce::DB::DSL do
       expect(mapping.fields).to_equal fields
     end
   end
+
+  describe "#converts" do
+    let(:adapter) { boolean_adapter }
+    let(:conversions) { { some: adapter } }
+
+    it "sets the conversions for the created mapping" do
+      dsl.converts conversions
+      expect(mapping.conversions).to_equal conversions
+    end
+
+    describe "when the adapter does not define the expected methods" do
+      let(:adapter) { Object.new }
+
+      it "raises an ArgumentError" do
+        expect(-> { dsl.converts conversions }).to_raise ArgumentError
+      end
+    end
+  end
 end

data/test/support/utilities.rb

@@ -26,3 +26,18 @@ def mappings!
     end
   end
 end
+
+# :nodoc:
+def boolean_adapter
+  Object.new.tap do |object|
+
+    def object.to_database(value)
+      value == "Yes"
+    end
+
+    def object.to_salesforce(value)
+      value ? "Yes" : "No"
+    end
+
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: restforce-db
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrew Horner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-04-13 00:00:00.000000000 Z
+date: 2015-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord