delta 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b03dae554a7f32d4fc3826fd35aa36f82549c2b1
-  data.tar.gz: 9b0bf35d479c98b32d2eacc38c4f71128464a2ea
+  metadata.gz: 030d9b3e370fd7a222a7b065e0340056a93a3ec8
+  data.tar.gz: 898fff561d39066111462b0e7c6dfc233c5c6bea
 SHA512:
-  metadata.gz: 55edc3a5987c896b0c296db1171a39bf80a24ada940b7bdaa59a5d5ba5464971f4ccbccfc206bd0e4bd5e330684b8c96d21124667eaf812e4bae0ce71eabb4d7
-  data.tar.gz: ad09180100f9018bd3feee520ae5343512d7a174efc6f633bac594650ed3d15af965196321b1cc04efdc3b1bf28739210c6b4323faed9ccb6d507f261eaf69cc
+  metadata.gz: f45a17ae319a21011519c0c0d6d804e630e39e425baf30484df5b19d8dc4fb21e8ffe9e8e81a5db390ce82c9795dd92be0fb432fe0182a4f88db83c92fa2161f
+  data.tar.gz: 6ea4a6e6154f88f5901bc1f61b7ba03745f20922a1ed584549762ebf5316d590a75f6c704579e3656f1e330c8667ede3de482bf71f8d34fd82f782793f0c111c

data/README.md

@@ -31,109 +31,97 @@ delta.deletions.to_a
 ]
 ```
 
-## Pluck
+## Identifiers
 
-Sometimes, you'll only be interested in a few of the attributes on an object.
-Delta supports `pluck`, which selects only the attributes you're interested in,
-instead of returning full objects:
+By default, Delta uses
+[object_id](http://ruby-doc.org/core-2.2.2/Object.html#method-i-object_id) to
+compare the collections. You can tell Delta to use something else by setting the
+`identifiers` parameter:
 
 ```ruby
 delta = Delta.new(
   from: [pikachu, pidgey, magikarp],
   to: [raichu, pidgey, butterfree],
-  pluck: [:name, :species]
+  identifiers: [:name]
 )
 
 delta.additions.to_a
-#=> [
-  #<struct name="Zappy", species="Pikachu">,
-  #<struct name="Flappy", species="Butterfree">
-]
+#=> [#<Pokemon @species="Butterfree", @name="Flappy", @type="Flying">]
 
 delta.deletions.to_a
-#=> [
-  #<struct name="Zappy", species="Raichu">,
-  #<struct name="Splashy", species="Magikarp">
-]
+#=> [#<Pokemon @species="Magikarp", @name="Splashy", @type="Water">]
 ```
 
+In this case, 'Raichu' and 'Pikachu' don't appear in the additions or deletions
+because they share the same name and Delta thinks that they are the same object.
+
 ## Modifications
 
 In most cases, it is more appropriate to think in terms of modifications rather
-than additions and deletions. In the example above, 'Pikachu' appeared as a
-deletion and 'Raichu' appeared as an addition. It might make more sense to model
-this as a modification, i.e. 'Zappy' changing its 'species'.
+than additions and deletions.
 
-Delta supports setting the `keys` that uniquely identify each object in the
-collection:
+To calculate modifications, Delta needs to know which things might change on the
+objects. You can tell Delta which things are subject to change by setting the
+`changes` parameter:
 
 ```ruby
 delta = Delta.new(
   from: [pikachu, pidgey, magikarp],
   to: [raichu, pidgey, butterfree],
-  pluck: [:species, :name],
-  keys: [:name]
+  identifiers: [:name],
+  changes: [:species]
 )
 
 delta.additions.to_a
-#=> [#<struct species="Butterfree", name="Flappy">]
+#=> [#<Pokemon @species="Butterfree", @name="Flappy", @type="Flying">]
 
 delta.modifications.to_a
-#=> [#<struct species="Raichu", name="Zappy">]
+#=> [#<Pokemon @species="Raichu", @name="Zappy", @type="Electric">]
 
 delta.deletions.to_a
-#=> [#<struct species="Magikarp", name="Splashy">]
+#=> [#<Pokemon @species="Magikarp", @name="Splashy", @type="Water">]
 ```
 
-You should specify which attributes to `pluck` so that Delta can distinguish
-between objects that have changed and objects that have not changed, but appear
-in both collections.
-
-If you do not specifiy any attributes to `pluck`, Delta will fall back to using
-object equality to determine which objects have changed. For ActiveRecord
-relations, Delta will use the database id as its fall back as it is more
-performant to do so.
+In the above example, 'Zappy' appears as a modification because Delta thinks
+that 'Pikachu' and 'Raichu' are the same object because they share the same
+name.
 
 ## Composite Keys
 
 In some cases, objects will be uniquely identified by a combination of things.
 For example, consider an application that enforces the uniqueness of names, but
-only in the context of a 'type'. This would mean that two Pokemon can have the
-same name, as long as they are not of the same type (e.g. 'Water').
+only in the context of a 'type'.
 
-In these cases, you can specify multiple keys:
+In these cases, you can specify multiple `identifiers`:
 
 ```ruby
 delta = Delta.new(
   from: [pikachu, pidgey, magikarp],
   to: [raichu, pidgey, butterfree],
-  pluck: [:species, :name, :type],
-  keys: [:name, :type] # <--
+  identifiers: [:name, :type]
+  changes: [:species]
 )
 
 delta.additions.to_a
-#=> [#<struct species="Butterfree", name="FANG!", type="Flying">]
+#=> [#<Pokemon @species="Butterfree", @name="FANG!", @type="Flying">]
 
 delta.modifications.to_a
-#=> [#<struct species="Raichu", name="Zappy", type="Electric">]
+#=> [#<Pokemon @species="Raichu", @name="Zappy", @type="Electric">]
 
 delta.deletions.to_a
-#=> [#<struct species="Magikarp", name="FANG!", type="Water">]
+#=> [#<Pokemon @species="Magikarp", @name="FANG!", @type="Water">]
 ```
 
-Consider the alternative where 'name' is used as the only key. This would mean
-that the Pokemon with species' 'Butterfree' and 'Magikarp' would be considered
-the same. This is semantically incorrect for this particular domain.
-
-TODO: What would happen if you did that? Should it raise an error?
+If 'name' were the only identifier, Delta would think that 'Butterfree' and
+'Magikarp' are the same object and they would not appear in additions or
+deletions.
 
-## Many-to-one Deltas
+## Many to One
 
-By combining the use of `pluck` and `keys`, you can build deltas that aren't
-necessarily related to a single object, but instead span multiple objects within
-the collection.
+It is possible to build deltas that aren't necessarily related to a single
+object, but instead, span multiple objects within the collections.
 
-This may be useful if there are objects in your collections that share some
+This may be useful if there are objects in your collection that share some
 property. In this example, all of the Pokemon have a 'type'. We can build a
 Delta that shows the difference in types between collections, like so:
 
@@ -141,8 +129,7 @@ Delta that shows the difference in types between collections, like so:
 delta = Delta.new(
   from: [pikachu, pidgey, magikarp],
   to: [raichu, pidgey, butterfree],
-  keys: [:type],
-  pluck: [:type]
+  identifiers: [:type]
 )
 
 delta.additions.to_a
@@ -152,19 +139,19 @@ delta.modifications.to_a
 #=> []
 
 delta.deletions.to_a
-#=> [#<struct type="Water">]
+#=> [#<Pokemon @species="Magikarp", @name="Splashy", @type="Water">]
 ```
 
 In this example, both 'Electric' and 'Flying' types appear in both collections.
-The only difference is the deletion of all 'Water' type Pokemon as a result of
-removing 'Magikarp' from the first collection.
+The only difference is the deletion of all 'Water' type Pokemon. Note that Delta
+will only return the first object that matches the deleted type.
 
 ## Rails Support
 
-Delta has added support for Rails applications. If the given collections are of
-class ActiveRecord::Relation, Delta will try to improve performance by reducing
-the number of select queries on the database. This isn't perfect and may not
-work with old versions of Rails.
+Delta has added support for Rails applications. If the collections are of class
+ActiveRecord::Relation, Delta will try to improve performance by reducing the
+number of select queries on the database. This may not work with old versions of
+Rails.
 
 ## In the Wild
 

data/lib/delta/base.rb

@@ -1,38 +1,38 @@
 class Delta
-  def initialize(from:, to:, pluck: nil, keys: nil)
-    identifier = keys ? Identifier.new(keys) : Identifier::Null.new
-    self.set = SetOperator.adapt(a: from, b: to, identifier: identifier)
-    self.plucker = pluck ? Plucker.new(pluck) : Plucker::Null.new
+  def initialize(from:, to:, identifiers: nil, changes: [])
+    self.set = SetOperator.adapt(
+      a: from,
+      b: to,
+      identifiers: identifiers,
+      changes: changes
+    )
   end
 
   def additions
     Enumerator.new do |y|
-      set.subtract_a_from_b.each do |b|
-        y.yield plucker.pluck(b)
+      set.b_minus_a.each do |b|
+        y.yield b
       end
     end
   end
 
   def modifications
     Enumerator.new do |y|
-      set.intersection.each do |a, b|
-        a_attributes = plucker.pluck(a)
-        b_attributes = plucker.pluck(b)
-
-        y.yield b_attributes unless a_attributes == b_attributes
+      set.intersection.each do |b|
+        y.yield b
       end
     end
   end
 
   def deletions
     Enumerator.new do |y|
-      set.subtract_b_from_a.each do |a|
-        y.yield plucker.pluck(a)
+      set.a_minus_b.each do |a|
+        y.yield a
       end
     end
   end
 
   private
 
-  attr_accessor :set, :plucker
+  attr_accessor :set
 end

data/lib/delta/set_operator/active_record.rb

@@ -5,41 +5,85 @@ class Delta
         a.is_a?(b.class) && a.class.name.include?("ActiveRecord")
       end
 
+      def initialize(a:, b:, identifiers: nil, changes:)
+        super
+
+        self.identifiers = identifiers || [:id]
+      end
+
       private
 
-      def subtract(a, b)
-        a.where.not(identifier.identities(b))
+      def subtract(a_scope, b_scope)
+        a = arel_table(a_scope, "a")
+        b = arel_table(b_scope, "b")
+
+        query = build_query(a_scope, b_scope, left_join)
+
+        query = query.project(a[Arel.star])
+        query = query.where(b[identifiers.first].eq(nil))
+
+        execute(query, a_scope)
       end
 
-      def intersect(a, b)
-        keys = identity_keys(a)
+      def intersect(a_scope, b_scope)
+        return [] if changes.empty?
+
+        a = arel_table(a_scope, "a")
+        b = arel_table(b_scope, "b")
+
+        query = build_query(a_scope, b_scope, inner_join)
+
+        query = query.project(Arel.star)
+        query = query.where(attribute_clause(a, b))
+
+        execute(query, a_scope)
+      end
 
-        a_records = left_of_intersection(a, b)
-        a_records = unique_records(a_records, keys)
+      def build_query(a_scope, b_scope, join_type)
+        a_query = nested_query(a_scope, "a")
+        b_query = nested_query(b_scope, "b")
+
+        a = arel_table(a_scope, "a")
+        b = arel_table(b_scope, "b")
+
+        query = a.from(a_query)
+        query = query.join(b.join(b_query).join_sources, join_type)
+        query = query.on(*identity_clauses(a, b))
+        query = query.group(*group_clauses(a, b))
+
+        query
+      end
+
+      def identity_clauses(a, b)
+        identifiers.map { |k| a[k].eq(b[k]) }
+      end
+
+      def attribute_clause(a, b)
+        changes.map { |k| a[k].not_eq(b[k]) }.inject(&:or)
+      end
+
+      def group_clauses(a, _b)
+        identifiers.map { |k| a[k] }
+      end
 
-        Enumerator.new do |y|
-          a_records.each do |record|
-            y.yield find_pair!(record, keys)
-          end
-        end
+      def execute(query, scope)
+        scope.model.find_by_sql(query.to_sql)
       end
 
-      def identity_keys(collection)
-        identifier.identities(collection).keys
+      def arel_table(scope, name)
+        Arel::Table.new(scope.arel_table.name, as: name)
       end
 
-      def left_of_intersection(a, b)
-        b_identities = identifier.identities(b)
-        a.where(b_identities)
+      def nested_query(scope, name)
+        Arel.sql("(#{scope.to_sql}) as #{name}")
       end
 
-      def unique_records(collection, keys)
-        collection.select(*keys).distinct
+      def left_join
+        Arel::Nodes::OuterJoin
       end
 
-      def find_pair!(record, keys)
-        attributes = record.slice(*keys)
-        [a.find_by!(attributes), b.find_by!(attributes)]
+      def inner_join
+        Arel::Nodes::InnerJoin
       end
     end
   end

data/lib/delta/set_operator/enumerable.rb

@@ -5,9 +5,10 @@ class Delta
         true
       end
 
-      def initialize(a:, b:, identifier:)
+      def initialize(a:, b:, identifiers: nil, changes:)
         super
 
+        self.identifiers = identifiers || [:object_id]
         self.a = a.lazy
         self.b = b.lazy
       end
@@ -19,15 +20,48 @@ class Delta
       end
 
       def intersect(a, b)
+        return [] if changes.empty?
+
+        pairs = pairs(a, b).reject do |a_object, b_object|
+          attributes(a_object) == attributes(b_object)
+        end
+
+        pairs.map { |_, b_object| b_object }
+      end
+
+      def pairs(a, b)
         a.map { |a_object| [a_object, other_object(b, a_object)] }
           .select { |_, b_object| b_object }
       end
 
       def other_object(collection, object)
-        identity = identifier.identity(object)
+        identity = identity(object)
 
         collection.find do |other_object|
-          identity == identifier.identity(other_object)
+          identity == identity(other_object)
+        end
+      end
+
+      def identity(object)
+        cache(:identity, object) do
+          identifiers.map { |m| object.public_send(m) }
+        end
+      end
+
+      def attributes(object)
+        cache(:attributes, object) do
+          changes.map { |m| object.public_send(m) }
+        end
+      end
+
+      def cache(name, key)
+        @cache ||= {}
+        @cache[name] ||= {}
+
+        if @cache[name].key?(key)
+          @cache[name][key]
+        else
+          @cache[name][key] = yield
         end
       end
     end

data/lib/delta/set_operator.rb

@@ -2,25 +2,31 @@ class Delta
   class SetOperator
     ADAPTERS = [ActiveRecord, Enumerable]
 
-    def self.adapt(a:, b:, identifier:)
+    def self.adapt(a:, b:, identifiers:, changes:)
       adapter = ADAPTERS.find { |klass| klass.compatible?(a, b) }
       adapter = ADAPTERS.last unless adapter
 
-      adapter.new(a: a, b: b, identifier: identifier)
+      adapter.new(
+        a: a,
+        b: b,
+        identifiers: identifiers,
+        changes: changes
+      )
     end
 
-    def initialize(a:, b:, identifier:)
+    def initialize(a:, b:, identifiers:, changes:)
       self.a = a
       self.b = b
-      self.identifier = identifier
+      self.identifiers = identifiers
+      self.changes = changes
     end
 
-    def subtract_a_from_b
-      subtract(b, a)
+    def a_minus_b
+      subtract(a, b)
     end
 
-    def subtract_b_from_a
-      subtract(a, b)
+    def b_minus_a
+      subtract(b, a)
     end
 
     def intersection
@@ -29,7 +35,7 @@ class Delta
 
     protected
 
-    attr_accessor :a, :b, :identifier
+    attr_accessor :a, :b, :identifiers, :changes
 
     private
 

data/lib/delta.rb

@@ -2,5 +2,3 @@ require "delta/base"
 require "delta/set_operator/enumerable"
 require "delta/set_operator/active_record"
 require "delta/set_operator"
-require "delta/plucker"
-require "delta/identifier"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: delta
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Chris Patuzzo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-24 00:00:00.000000000 Z
+date: 2015-05-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -104,7 +104,6 @@ files:
 - lib/delta.rb
 - lib/delta/base.rb
 - lib/delta/identifier.rb
-- lib/delta/plucker.rb
 - lib/delta/set_operator.rb
 - lib/delta/set_operator/active_record.rb
 - lib/delta/set_operator/enumerable.rb

data/lib/delta/plucker.rb

@@ -1,23 +0,0 @@
-class Delta
-  class Plucker
-    def initialize(pluck)
-      self.array = pluck
-      self.struct = Struct.new(*array)
-    end
-
-    def pluck(object)
-      attributes = array.map { |k| object.public_send(k) }
-      struct.new(*attributes)
-    end
-
-    private
-
-    attr_accessor :array, :struct
-
-    class Null
-      def pluck(object)
-        object
-      end
-    end
-  end
-end