restforce-db 1.0.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: dfc392eb1d43c78cb82873f3462c77f92040cac1
-  data.tar.gz: aaa229b2207cbf203dad3fb10bb65d407afae437
+  metadata.gz: 8e6b77ef750532361625bbec55ad4a00e1ae4d21
+  data.tar.gz: b88d477b1e2a2ea7f2e301b35c54b08d77612bb4
 SHA512:
-  metadata.gz: f35c317c7c078428840092490997eadad217291452f0087c720cc9930788a6063cff4ca430db559c3ec01082a0fcea21a3612199fc77abb09f04ab56ff9dfa1e
-  data.tar.gz: 27c60936fdd1edc90989c184b29aa75664f0dcff228bd8b306b22a5958070632530344e5b908595a24a2100a4c714c5f379148a492c01fae317edb116c5034d3
+  metadata.gz: 89a255caf32a25c81b24415bd5d7b389a19219e0055b7af73f3c59388a1b0914f8eb827dfe48752f528a46b65f766fb8ab9060261a6a116460b43575032da136
+  data.tar.gz: 53d5e840aeaee28b666979b7a97e31f85bebd7bcd6bb6d6611f125f3bc6ae7c995de187749680d19ee6fdb51c3b0728ec03ae6069aad68429201fca0d444fc4d

data/README.md

@@ -39,11 +39,13 @@ To register a Salesforce mapping in an `ActiveRecord` model, you'll need to add
 class Restaurant < ActiveRecord::Base
 
   include Restforce::DB::Model
-  has_one :specialty, class_name: "Dish"
+  has_one :chef, inverse_of: :restaurant
+  has_many :dishes, inverse_of: :restaurant
 
   sync_with("Restaurant__c", :always) do
     where "StarRating__c > 4"
-    belongs_to :specialty, through: %w(Specialty__c KeyIngredient__c)
+    has_many :dishes, through: "Restaurant__c"
+    belongs_to :chef, through: %w(Chef__c Cuisine__c)
     maps(
       name:  "Name",
       style: "Style__c",
@@ -52,26 +54,33 @@ class Restaurant < ActiveRecord::Base
 
 end
 
-class Dish < ActiveRecord::Base
+class Chef < ActiveRecord::Base
 
   include Restforce::DB::Model
-  belongs_to :restaurant
+  belongs_to :restaurant, inverse_of: :chef
 
-  sync_with("Dish__c", :passive) do
-    has_one :restaurant, through: "Specialty__c"
-    maps(
-      name:   "Name",
-      origin: "Origin__c",
-    )
+  sync_with("Contact", :passive) do
+    has_one :restaurant, through: "Chef__c"
+    maps name: "Name"
   end
 
-  sync_with("Ingredient__c", :passive) do
-    has_one :restaurant, through: "KeyIngredient__c"
-    maps(
-      key_ingredient: "Name",
-    )
+  sync_with("Cuisine__c", :passive) do
+    has_one :restaurant, through: "Cuisine__c"
+    maps style: "Name"
   end
 
+end
+
+class Dish < ActiveRecord::Base
+  
+  include Restforce::DB::Model
+  belongs_to :restaurant, inverse_of: :dishes
+
+  sync_with("Dish__c", :associated, with: :restaurant) do
+    belongs_to :restaurant, through: "Restaurant__c"
+    maps name: "Name"
+  end
+  
 end
 ```
 
@@ -95,7 +104,9 @@ A `passive` synchronization strategy will update all modified records that alrea
 
 ##### `:associated`
 
-_Coming Soon_
+An `associated` synchronization strategy will create any new records it encounters _if and only if the named association for that record has already been synchronized_. The association is specified via the `:with` option. In the above example, new `Dish`/`Dish__c` records will be synchronized when the record identified by `Restaurant__c` has already been synchronized.
+
+This allows for the selective addition of "relevant" records to the system over time.
 
 #### Lookup Conditions
 
@@ -117,22 +128,27 @@ If your Salesforce objects have parity with your ActiveRecord models, your assoc
 
 This defines an association type in which the Lookup (i.e., foreign key) _is on the mapped Salesforce model_. In the example above, the `Restaurant__c` object type in Salesforce has two Lookup fields:
 
-- `Specialty__c`, which corresponds to the `Dish__c` object type, and
-- `KeyIngredient__c`, which corresponds to the `Ingredient__c` object type
+- `Chef__c`, which corresponds to the `Contact` object type, and
+- `Cuisine__c`, which corresponds to the `Cuisine__c` object type
  
-Thus, the `Restaurant__c` mapping declares a `belongs_to` relationship to `:specialty`, with a `:through` argument referencing both of the Lookups used by the mappings on the associated `Dish` class.
+Thus, the `Restaurant__c` mapping declares a `belongs_to` relationship to `:chef`, with a `:through` argument referencing both of the Lookups used by the mappings on the associated `Chef` class.
 
 As shown above, the `:through` option may contain _an array of Lookup field names_, which may be useful if more than one mapping on the associated ActiveRecord model refers to a Lookup on the same Salesforce record.
 
 ##### `has_one`
 
-This defines an inverse relationship for a `belongs_to` relationship. In the example above, `Dish` defines _two_ `has_one` relationships with `:restaurant`, one for each mapping. The `:through` arguments for each call to `has_one` correspond to the relevant Lookup field on the parent object.
+This defines an inverse relationship for a `belongs_to` relationship. In the example above, `Chef` defines _two_ `has_one` relationships with `:restaurant`, one for each mapping. The `:through` arguments for each call to `has_one` correspond to the relevant Lookup field on the parent object.
 
-In the above example, given the relationships defined between our records, we can ascertain that `Restaurant__c.Specialty__c` is a `Lookup(Dish__c)` field in Salesforce, while ` Restaurant__c.KeyIngredient__c` is a `Lookup(Ingredient__c)`.
+In the above example, given the relationships defined between our records, we can ascertain that `Restaurant__c.Chef__c` is a `Lookup(Contact)` field in Salesforce, while `Restaurant__c.Cuisine__c` is a `Lookup(Cuisine__c)`.
 
 ##### `has_many`
 
-_Coming Soon_
+This _also_ defines an inverse relationship for a `belongs_to` relationship. The chief difference between this and `has_one` is that `has_many` relationships are one-to-many, rather than one-to-one.
+
+In the above example, `Dish__c` is a Salesforce object type which references the `Restaurant__c` object type through an aptly-named Lookup. There is no restriction on the number of `Dish__c` objects that may reference the same `Restaurant__c`, so we define this relationship as a `has_many` associaition in our `Restaurant` mapping.
+
+__NOTE__: Unlike `has_one` associations, `has_many` associations do not currently support multiple lookups from the same model. The Lookup is assumed
+to always refer to the `Id` of the parent object.
 
 ### Run the daemon
 

data/lib/restforce/db/associations/base.rb

@@ -0,0 +1,152 @@
+module Restforce
+
+  module DB
+
+    module Associations
+
+      # Restforce::DB::Associations::Base defines an association between two
+      # mappings in the Registry.
+      class Base
+
+        attr_reader :name, :lookup
+
+        # Public: Initialize a new Restforce::DB::Associations::Base.
+        #
+        # name    - The name of the ActiveRecord association to construct.
+        # through - The name of the lookup field on the Salesforce record.
+        def initialize(name, through: nil)
+          @name = name.to_sym
+          @lookup = through.is_a?(Array) ? through.map(&:to_s) : through.to_s
+        end
+
+        # Public: Build a record or series of records for the association
+        # defined by this class. Must be overridden in subclasses.
+        #
+        # Raises a NotImplementedError.
+        def build(_database_record, _salesforce_record)
+          raise NotImplementedError
+        end
+
+        # Public: Get a list of fields which should be included in the
+        # Salesforce record's lookups for any mapping including this
+        # association.
+        #
+        # Returns a list of Salesforce fields this record should return.
+        def fields
+          [*lookup]
+        end
+
+        # Public: Has a record for this association already been synchronized
+        # for the supplied instance?
+        #
+        # instance - A Restforce::DB::Instances::Base.
+        #
+        # Returns a Boolean.
+        def synced_for?(instance)
+          base_class = instance.mapping.database_model
+          reflection = base_class.reflect_on_association(name)
+          association_id = associated_salesforce_id(instance)
+
+          return false unless association_id
+          reflection.klass.exists?(
+            mapping_for(reflection).lookup_column => association_id,
+          )
+        end
+
+        private
+
+        # Internal: Get the appropriate Salesforce Lookup ID field for the
+        # passed mapping.
+        #
+        # mapping         - A Restforce::DB::Mapping.
+        # database_record - An instance of an ActiveRecord::Base subclass.
+        #
+        # Returns a String.
+        def lookup_field(mapping, database_record)
+          inverse = inverse_association_name(target_reflection(database_record))
+          mapping.associations.detect { |a| a.name == inverse }.lookup
+        end
+
+        # Internal: Get the class of the inverse ActiveRecord association.
+        #
+        # database_record - An instance of an ActiveRecord::Base subclass.
+        #
+        # Returns a Class.
+        def target_class(database_record)
+          target_reflection(database_record).klass
+        end
+
+        # Internal: Get an AssociationReflection for this association on the
+        # passed database record.
+        #
+        # database_record - An instance of an ActiveRecord::Base subclass.
+        #
+        # Returns an ActiveRecord::AssociationReflection.
+        def target_reflection(database_record)
+          database_record.class.reflect_on_association(name)
+        end
+
+        # Internal: Get the name of the inverse association which corresponds
+        # to this one.
+        #
+        # reflection - An ActiveRecord::AssociationReflection.
+        #
+        # Returns a Symbol.
+        def inverse_association_name(reflection)
+          reflection.send(:inverse_name)
+        end
+
+        # Internal: Get the first mapping which corresponds to an ActiveRecord
+        # reflection.
+        #
+        # reflection - An ActiveRecord::AssociationReflection.
+        #
+        # Returns a Restforce::DB::Mapping.
+        def mapping_for(reflection)
+          inverse = inverse_association_name(reflection)
+          Registry[reflection.klass].detect do |mapping|
+            mapping.associations.any? { |a| a.name == inverse }
+          end
+        end
+
+        # Internal: Get the first association which corresponds to an
+        # ActiveRecord reflection.
+        #
+        # reflection - An ActiveRecord::AssociationReflection.
+        #
+        # Returns a Restforce::DB::Associations::Base.
+        def association_for(reflection)
+          inverse = reflection.send(:inverse_name)
+          Registry[reflection.klass].detect do |mapping|
+            association = mapping.associations.detect { |a| a.name == inverse }
+            break association if association
+          end
+        end
+
+        # Internal: Get an ActiveRecord::Relation scope for the passed record's
+        # association.
+        #
+        # database_record - An instance of an ActiveRecord::Base subclass.
+        #
+        # Returns an ActiveRecord scope.
+        def association_scope(database_record)
+          database_record.association(name).scope
+        end
+
+        # Internal: Get the Salesforce ID belonging to the associated record
+        # for a supplied instance. Must be implemented per-association.
+        #
+        # instance - A Restforce::DB::Instances::Base
+        #
+        # Returns a String.
+        def associated_salesforce_id(_instance)
+          raise NotImplementedError
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/associations/belongs_to.rb

@@ -0,0 +1,70 @@
+module Restforce
+
+  module DB
+
+    module Associations
+
+      # Restforce::DB::Associations::BelongsTo defines a relationship in which
+      # a Salesforce ID on the named database association exists on this
+      # Mapping's Salesforce record.
+      class BelongsTo < Base
+
+        # Public: Construct a database record from the Salesforce records
+        # associated with the supplied parent Salesforce record.
+        #
+        # database_record   - An instance of an ActiveRecord::Base subclass.
+        # salesforce_record - A Hashie::Mash representing a Salesforce object.
+        #
+        # Returns the constructed association record.
+        def build(database_record, salesforce_record)
+          lookups = {}
+
+          attributes = Registry[target_class(database_record)].inject({}) do |hash, mapping|
+            lookup_id = salesforce_record[lookup_field(mapping, database_record)]
+
+            lookups[mapping.lookup_column] = lookup_id
+            hash.merge(attributes_for(mapping, lookup_id))
+          end
+
+          associated = association_scope(database_record).find_by(lookups)
+          associated ||= database_record.association(name).build(lookups)
+
+          associated.assign_attributes(attributes)
+          associated
+        end
+
+        private
+
+        # Internal: Get a database-ready Hash of attributes from the Salesforce
+        # record identified by the passed lookup ID.
+        #
+        # mapping   - A Restforce::DB::Mapping.
+        # lookup_id - A Lookup ID for the Salesforce record type in the Mapping.
+        #
+        # Returns a Hash.
+        def attributes_for(mapping, lookup_id)
+          salesforce_instance = mapping.salesforce_record_type.find(lookup_id)
+          mapping.convert(mapping.database_model, salesforce_instance.attributes)
+        end
+
+        # Internal: Get the Salesforce ID belonging to the associated record
+        # for a supplied instance. Must be implemented per-association.
+        #
+        # instance - A Restforce::DB::Instances::Base
+        #
+        # Returns a String.
+        def associated_salesforce_id(instance)
+          reflection = instance.mapping.database_model.reflect_on_association(name)
+          inverse_association = association_for(reflection)
+
+          salesforce_instance = instance.mapping.salesforce_record_type.find(instance.id)
+          salesforce_instance.record[inverse_association.lookup] if salesforce_instance
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/associations/foreign_key.rb

@@ -0,0 +1,80 @@
+module Restforce
+
+  module DB
+
+    module Associations
+
+      # Restforce::DB::Associations::ForeignKey defines a relationship in which
+      # the Salesforce IDs for any associated record(s) are present on a foreign
+      # record type.
+      class ForeignKey < Base
+
+        # Public: Get a list of fields which should be included in the
+        # Salesforce record's lookups for any mapping including this
+        # association.
+        #
+        # Returns a list of Salesforce fields this record should return.
+        def fields
+          []
+        end
+
+        private
+
+        # Internal: Identify the inverse mapping for this relationship by
+        # looking it up through the target association.
+        #
+        # database_record - An instance of an ActiveRecord::Base subclass.
+        #
+        # Returns a Restforce::DB::Mapping.
+        def target_mapping(database_record)
+          inverse = inverse_association_name(target_reflection(database_record))
+          Registry[target_class(database_record)].detect do |mapping|
+            mapping.associations.any? { |a| a.name == inverse }
+          end
+        end
+
+        # Internal: Construct a single associated record from the supplied
+        # Salesforce instance.
+        #
+        # database_record     - An instance of an ActiveRecord::Base subclass.
+        # salesforce_instance - A Restforce::DB::Instances::Salesforce.
+        #
+        # Returns the constructed object.
+        def construct_for(database_record, salesforce_instance)
+          mapping = salesforce_instance.mapping
+          lookups = { mapping.lookup_column => salesforce_instance.id }
+          associated = association_scope(database_record).find_by(lookups)
+          associated ||= database_record.association(name).build(lookups)
+
+          attributes = mapping.convert(
+            associated.class,
+            salesforce_instance.attributes,
+          )
+
+          associated.assign_attributes(attributes)
+          associated
+        end
+
+        # Internal: Get the Salesforce ID belonging to the associated record
+        # for a supplied instance. Must be implemented per-association.
+        #
+        # instance - A Restforce::DB::Instances::Base
+        #
+        # Returns a String.
+        def associated_salesforce_id(instance)
+          query = "#{lookup} = '#{instance.id}'"
+
+          reflection = instance.mapping.database_model.reflect_on_association(name)
+          inverse_mapping = mapping_for(reflection)
+
+          salesforce_instance = inverse_mapping.salesforce_record_type.first(query)
+          salesforce_instance.id if salesforce_instance
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/associations/has_many.rb

@@ -0,0 +1,37 @@
+module Restforce
+
+  module DB
+
+    module Associations
+
+      # Restforce::DB::Associations::HasMany defines a relationship in which
+      # potentially several Salesforce records maintain a reference to the
+      # Salesforce record on the current Mapping.
+      class HasMany < ForeignKey
+
+        # Public: Construct a database record for each Salesforce record
+        # associated with the supplied parent Salesforce record.
+        #
+        # database_record   - An instance of an ActiveRecord::Base subclass.
+        # salesforce_record - A Hashie::Mash representing a Salesforce object.
+        #
+        # Returns the constructed association records.
+        def build(database_record, salesforce_record)
+          target = target_mapping(database_record)
+          lookup_id = "#{lookup_field(target, database_record)} = '#{salesforce_record.Id}'"
+
+          records = []
+          target.salesforce_record_type.each(conditions: lookup_id) do |instance|
+            records << construct_for(database_record, instance)
+          end
+
+          records
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/associations/has_one.rb

@@ -0,0 +1,33 @@
+module Restforce
+
+  module DB
+
+    module Associations
+
+      # Restforce::DB::Associations::HasOne defines a relationship in which a
+      # Salesforce ID for this Mapping's database record exists on the named
+      # database association's Mapping.
+      class HasOne < ForeignKey
+
+        # Public: Construct a database record from a single Salesforce record
+        # associated with the supplied parent Salesforce record.
+        #
+        # database_record   - An instance of an ActiveRecord::Base subclass.
+        # salesforce_record - A Hashie::Mash representing a Salesforce object.
+        #
+        # Returns the constructed association record.
+        def build(database_record, salesforce_record)
+          target = target_mapping(database_record)
+          query = "#{lookup_field(target, database_record)} = '#{salesforce_record.Id}'"
+
+          instance = target.salesforce_record_type.first(query)
+          construct_for(database_record, instance)
+        end
+
+      end
+
+    end
+
+  end
+
+end

data/lib/restforce/db/dsl.rb

@@ -35,31 +35,43 @@ module Restforce
       # Public: Define a relationship in which the current mapping contains the
       # lookup ID for another mapping.
       #
-      # TODO: This should eventually be implemented as a full-fledged
-      # association on the mapping. Something like:
-      # @mapping.associate(association, Associations::BelongsTo, options)
-      #
       # association - The name of the ActiveRecord association.
-      # options     - A Hash of options to pass to the association.
+      # through     - A String or Array of Strings representing the Lookup IDs.
       #
       # Returns nothing.
-      def belongs_to(association, options)
-        @mapping.associations[association] = options[:through]
+      def belongs_to(association, through:)
+        @mapping.associations << Associations::BelongsTo.new(
+          association,
+          through: through,
+        )
       end
 
       # Public: Define a relationship in which the current mapping is referenced
       # by one object through a lookup ID on another mapping.
       #
-      # TODO: This should eventually be implemented as a full-fledged
-      # association on the mapping. Something like:
-      # @mapping.associate(association, Associations::HasOne, options)
+      # association - The name of the ActiveRecord association.
+      # through     - A String representing the Lookup ID.
+      #
+      # Returns nothing.
+      def has_one(association, through:) # rubocop:disable PredicateName
+        @mapping.associations << Associations::HasOne.new(
+          association,
+          through: through,
+        )
+      end
+
+      # Public: Define a relationship in which the current mapping is referenced
+      # by many objects through a lookup ID on another mapping.
       #
       # association - The name of the ActiveRecord association.
-      # options     - A Hash of options to pass to the association.
+      # through     - A String representing the Lookup ID.
       #
       # Returns nothing.
-      def has_one(_association, options) # rubocop:disable PredicateName
-        @mapping.through = options[:through]
+      def has_many(association, through:) # rubocop:disable PredicateName
+        @mapping.associations << Associations::HasMany.new(
+          association,
+          through: through,
+        )
       end
 
       # Public: Define a set of fields which should be synchronized between the

data/lib/restforce/db/mapping.rb

@@ -28,7 +28,6 @@ module Restforce
         :fields,
         :associations,
         :conditions,
-        :through,
         :strategy,
       )
 
@@ -44,8 +43,8 @@ module Restforce
         @database_record_type = RecordTypes::ActiveRecord.new(database_model, self)
         @salesforce_record_type = RecordTypes::Salesforce.new(salesforce_model, self)
 
-        self.associations = {}
         self.fields = {}
+        self.associations = []
         self.conditions = []
         self.strategy = strategy
       end
@@ -55,7 +54,7 @@ module Restforce
       #
       # Returns an Array.
       def salesforce_fields
-        fields.values + associations.values.flatten
+        fields.values + associations.map(&:fields).flatten
       end
 
       # Public: Get a list of the relevant database column names for this

data/lib/restforce/db/record_types/active_record.rb

@@ -17,17 +17,12 @@ module Restforce
         # Returns a Restforce::DB::Instances::ActiveRecord instance.
         # Raises on any validation or database error.
         def create!(from_record)
-          attributes = @mapping.convert(@record_type, from_record.attributes)
-
-          record = @record_type.new(attributes.merge(@mapping.lookup_column => from_record.id))
-
-          associations = @mapping.associations.map do |association, _|
-            Associations::ActiveRecord.new(record, association).build(from_record.record)
-          end
+          record = @record_type.find_or_initialize_by(@mapping.lookup_column => from_record.id)
+          record.assign_attributes(@mapping.convert(@record_type, from_record.attributes))
+          associations = @mapping.associations.flat_map { |a| a.build(record, from_record.record) }
 
           record.transaction do
             record.save!
-
             # We touch the synchronization timestamps here to ensure that they
             # exceed the last updated timestamp.
             associations.each { |association| association.touch(:synchronized_at) }

data/lib/restforce/db/record_types/salesforce.rb

@@ -25,26 +25,40 @@ module Restforce
           find(record_id)
         end
 
-        # Public: Find the Salesforce record corresponding to the passed id.
+        # Public: Find the first Salesforce record which meets the passed
+        # conditions.
         #
-        # id - The id of the record in Salesforce.
+        # conditions - One or more String query conditions
         #
         # Returns nil or a Restforce::DB::Instances::Salesforce instance.
-        def find(id)
-          record = DB.client.query(query("Id = '#{id}'")).first
+        def first(*conditions)
+          record = DB.client.query(query(conditions)).first
           return unless record
 
           Instances::Salesforce.new(@record_type, record, @mapping)
         end
 
+        # Public: Find the Salesforce record corresponding to the passed id.
+        #
+        # id - The id of the record in Salesforce.
+        #
+        # Returns nil or a Restforce::DB::Instances::Salesforce instance.
+        def find(id)
+          first("Id = '#{id}'")
+        end
+
         # Public: Iterate through all Salesforce records of this type.
         #
         # options - A Hash of options which should be applied to the set of
         #           fetched records. Allowed options are:
-        #           :before - A Time object defining the most recent update
-        #                     timestamp for which records should be returned.
-        #           :after  - A Time object defining the least recent update
-        #                     timestamp for which records should be returned.
+        #           :before     - A Time object defining the most recent update
+        #                         timestamp for which records should be
+        #                         returned.
+        #           :after      - A Time object defining the least recent update
+        #                         timestamp for which records should be
+        #                         returned.
+        #           :conditions - An Array of conditions to append to the lookup
+        #                         query.
         #
         # Yields a series of Restforce::DB::Instances::Salesforce instances.
         # Returns nothing.
@@ -52,6 +66,7 @@ module Restforce
           constraints = [
             ("SystemModstamp < #{options[:before].utc.iso8601}" if options[:before]),
             ("SystemModstamp >= #{options[:after].utc.iso8601}" if options[:after]),
+            *options[:conditions],
           ]
 
           DB.client.query(query(*constraints)).each do |record|