tree_diff 1.1.0 → 1.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e3699e4d25cd4ef5e40056955c4cb5a72f34d022d91d0cdcf1987cc285f338be
-  data.tar.gz: 0f9da5732ba16921b1dfbd46e16051618787b6369a287536f8ced41c8a137282
+  metadata.gz: 36d4d811a88254040e9ccd3693b1e4c5e667cdf83c5cfa14b3ec1fa94a52f23f
+  data.tar.gz: 4e6ab356040d07e5db26f5f828456e4b52196e4202e39c32dfb3c17f8d23ef9d
 SHA512:
-  metadata.gz: 8183fd052ac83c3142b200caf071facbeb3be93585e184456f6d78a1967fda9986869997284e605221bc0111272bc018b77fbc5bc1f4d20a5417634f438c4e3c
-  data.tar.gz: dfb3b3ae7a125ecdba7224f1c5036499e81b2fbbc8bf9ceec9773a09796896c9e5c116816df78c198d5366a337dd86c118208d540645a72f51f55cda3640a2ae
+  metadata.gz: 6c067170e623ee334dea672c92f28ec2dc8692facc9d8a139353b541fc7ce67e0faef09dea321ea49465b31ff3b086f7e0f33c1970b43b6d7a8632fab1493ad4
+  data.tar.gz: 72c485c7563360466b9f82210c2ba7505a90d663a7569877597e9813c3ffdfeddca95e3cd017520d7b0319533f3895cda76bd02d938338a23fd2942c81fee7e9

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Gemfile

@@ -4,5 +4,5 @@ group :test do
   gem 'minitest'
   gem 'm'
   gem 'sqlite3'
-  gem 'activerecord'
+  gem 'activerecord', '~> 5.2'
 end

data/Gemfile.lock

@@ -31,7 +31,7 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
-  activerecord
+  activerecord (~> 5.2)
   m
   minitest
   sqlite3

data/README.md

@@ -0,0 +1,43 @@
+# Tree Diff
+
+Compare large object trees. Like a generic and standalone ActiveModel::Dirty, though completely ORM agnostic.
+
+## Installation
+
+```
+gem install tree_diff
+```
+
+## Getting Started
+
+1. Define a diff class that inherits from `TreeDiff`. Pass an array of hashes and arrays to define your object tree to `observe`.
+
+    This format is just like how sets of nested attributes are passed to strong params.
+
+    ```ruby
+    class MyDiffClass < TreeDiff
+      observe :status, :created_at, :user_id
+        items: [:status, :description, :cost],
+        starting_location: [:latitude, :longitude, :updated_at,
+                            address: [:city, :state, :country]
+    end
+    ```
+
+2. Instantiate your diff class and pass it the object you want to compare just before mutating it. For example, controller usage:
+
+    ```ruby
+    class ThingsController
+      def update
+        thing = Thing.find(params[:id])
+        my_diff = MyDiffClass.new(thing)
+
+        if thing.update(thing_params)
+          handle_stuff if my_diff.saw_any_change?
+          redirect_to thing, notice: 'Updated thing.'
+        else
+          # ...
+        end
+      end
+    end
+    ```
+

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.warning = true
+  test.pattern = 'test/**/*_test.rb'
+end
+
+task :default => :test

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 300) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/lib/tree_diff.rb

@@ -1,4 +1,5 @@
 class TreeDiff
+  # A container for each copied attribute from the source object by each path.
   Mold = Class.new
 
   class Change
@@ -11,36 +12,65 @@ class TreeDiff
     end
   end
 
-  def self.original_observations
-    class_variable_set(:@@original_observations, nil) unless class_variable_defined?(:@@original_observations)
-    class_variable_get(:@@original_observations)
-  end
-
-  def self.observations
-    class_variable_set(:@@observations, nil) unless class_variable_defined?(:@@observations)
-    class_variable_get(:@@observations)
-  end
-
-  def self.conditions
-    class_variable_set(:@@conditions, nil) unless class_variable_defined?(:@@conditions)
-    class_variable_get(:@@conditions)
-  end
-
+  # Defines the full tree of relationships and attributes this TreeDiff class observes. Pass a structure of arrays and
+  # hashes, similar to a strong_params `#permit` definition.
+  #
+  # ```
+  # class MyDiffClass < TreeDiff
+  #   observe :order_number, :available_at, line_items: [:description, :price, tags: [:name]]
+  # end
+  # ```
+  #
+  # @param [Array] defs Observation attribute definitions. Anything not in this list will be skipped by the diff.
+  # @return [void]
   def self.observe(*defs)
-    class_variable_set(:@@original_observations, defs)
-    class_variable_set(:@@observations, [])
+    class_variable_set(:@@observations, defs)
+    class_variable_set(:@@attribute_paths, [])
     observe_chain [], defs
   end
 
+  # Adds a condition to an attribute that dictates whether an attribute is compared. The given block is invoked
+  # just before trying to call the attribute to get a comparable value. Called twice per attribute, once for the
+  # old value and once for the new.
+  #
+  # @yieldparam original_object The original object being compared.
+  # @yieldreturn [Boolean] Whether this attribute should be compared.
+  #
+  # ```
+  # class MyDiffClass < TreeDiff
+  #   observe details: :order_status
+  #
+  #   condition [:details, :order_status] do |order|
+  #     order.order_status == 'delivered'
+  #   end
+  # end
+  #
+  # @return [void]
   def self.condition(path, &condition)
     class_variable_set(:@@conditions, []) unless conditions
     conditions << [path, condition]
   end
 
-  def self.condition_for(path)
-    return unless (condition = conditions.detect { |c| c.first == path })
+  # Holds the original object tree definitions passed to `.observe`.
+  # @return [Array]
+  def self.observations
+    class_variable_set(:@@observations, nil) unless class_variable_defined?(:@@observations)
+    class_variable_get(:@@observations)
+  end
 
-    condition.last # A stored block (proc)
+  # All paths to be walked expressed as arrays, ending in each observed attribute. These are generated upon
+  # calling `.observe`.
+  # @return [Array]
+  def self.attribute_paths
+    class_variable_set(:@@attribute_paths, nil) unless class_variable_defined?(:@@attribute_paths)
+    class_variable_get(:@@attribute_paths)
+  end
+
+  # All conditions defined via `.condition`.
+  # @return [Array]
+  def self.conditions
+    class_variable_set(:@@conditions, nil) unless class_variable_defined?(:@@conditions)
+    class_variable_get(:@@conditions)
   end
 
   def self.observe_chain(chain, attributes)
@@ -50,7 +80,7 @@ class TreeDiff
           observe_chain chain + [child_method], keep_as_array(child_attributes)
         end
       else
-        observations << chain + [method_name]
+        attribute_paths << chain + [method_name]
       end
     end
   end
@@ -61,32 +91,74 @@ class TreeDiff
   end
   private_class_method :keep_as_array
 
+  # Prepares a new comparision. Creates a mold/mock of the object being diffed as the 'old' state according to the
+  # relationship tree defined via `.observe`.  Each attribute's value is copied via serializing and deserializing
+  # via Marshal.
+  #
+  # @param original_object The object to be compared, before you mutate any of its attributes.
   def initialize(original_object)
     check_observations
 
     self.class.class_variable_set(:@@conditions, [])
-    @old_object_as_mold = create_mold Mold.new, original_object, self.class.original_observations
+    @old_object_as_mold = create_mold Mold.new, original_object, self.class.observations
     @current_object = original_object
   end
 
+  # Check if there is any change at all, otherwise each observed attribute is considered equal before and after
+  # the change.
+  # @return [Boolean] Whether there was a change
   def saw_any_change?
     changes.present?
   end
 
+  # Walk all observed paths and compare each resulting value. Returns a structure like:
+  #
+  # ```ruby
+  #   [{path: [:line_items, :description], old: ["thing", "other thing"], new: ["other thing", "new thing"]},
+  #    {path: [:line_items, :price_usd_cents], old: [1234, 5678], new: [5678, 1357]},
+  #    {path: [:line_items, :item_categories, :description], old: ['foo', 'bar'], new: ['foo']}]
+  # ```
+  #
+  # @return [Array] A list of each attribute that has changed. Each element is a hash with keys
+  #                 :path, :old, and :new.
   def changes
     iterate_observations(@old_object_as_mold, @current_object)
   end
 
+  # Compare all observed paths, find the given path, and check if its value has changed.
+  #
+  # @return [Boolean] Whether the path is changed.
+  def changed?(path)
+    changes_at(path).present?
+  end
+
+  # Walk all observed paths and compare each resulting value. Returns a structure like:
+  #
+  # @example Return all "old" values
+  #   diff = MyDiffClass.new(my_object)
+  #   # Mutate the object...
+  #   changes = diff.changes_as_objects
+  #
+  #   changes.map(&:old)
+  #
+  # @return [Array of TreeDiff::Change] A list of each attribute that has changed. Each element is an ojbect with
+  #                                     methods :path, :old, and :new.
   def changes_as_objects
     changes.map { |c| Change.new(c.fetch(:path), c.fetch(:old), c.fetch(:new)) }
   end
 
+  # Get a collection of changed paths only.
+  # @return [Array of Arrays]
   def changed_paths
     changes_as_objects.map(&:path)
   end
 
+  # Find a change by its path.
+  #
+  # @return [TreeDiff::Change] The change at the given path, or `nil` if no change.
   def changes_at(path)
-    changes_as_objects.detect { |c| c.path == path }
+    arrayed_path = Array(path)
+    changes_as_objects.detect { |c| c.path == arrayed_path }
   end
 
   private
@@ -96,7 +168,7 @@ class TreeDiff
       raise 'TreeDiff is an abstract class - write a child class with observations'
     end
 
-    if !self.class.original_observations || self.class.original_observations.empty?
+    if !self.class.observations || self.class.observations.empty?
       raise 'you need to define some observations first'
     end
   end
@@ -137,7 +209,7 @@ class TreeDiff
   end
 
   def iterate_observations(mold, current_object)
-    self.class.observations.each.with_object([]) do |path, changes|
+    self.class.attribute_paths.each.with_object([]) do |path, changes|
       old_obj_and_method = try_path mold, path
       new_obj_and_method = try_path current_object, path, mold
 
@@ -165,7 +237,7 @@ class TreeDiff
 
   def method_caller_with_condition(path)
     ->(object_and_method) do
-      condition = self.class.condition_for(path)
+      condition = condition_for(path)
 
       if !condition || condition.call(object_and_method.fetch(:receiver))
         object_and_method.fetch(:receiver).public_send(object_and_method.fetch(:method_name))
@@ -173,6 +245,13 @@ class TreeDiff
     end
   end
 
+  def condition_for(path)
+    return unless (condition = self.class.conditions.detect { |c| c.first == path })
+
+    condition.last # A stored block (proc)
+  end
+
+
   # By design this tries to be as loosely typed and flexible as possible. Sometimes, calling an attribute
   # name on a collection of them yields an enumerable object. For example, active record's enum column returns
   # a hash indicating the enumeration definition. That would lead to incorrectly comparing this value, a hash,

data/test/tree_diff_test.rb

@@ -1,5 +1,5 @@
 require_relative '../lib/tree_diff'
-require 'helper'
+require_relative 'helper'
 require 'minitest/autorun'
 
 class TreeDiffTest < Minitest::Test
@@ -38,6 +38,19 @@ class TreeDiffTest < Minitest::Test
 
     assert_equal [[:at]], diff.changed_paths
     assert_equal [{path: [:at], old: Time.gm(2000, 1, 1, 12, 30), new: Time.gm(2000, 1, 1, 1, 30)}], diff.changes
+
+    assert_equal true, diff.changed?([:at])
+    assert_equal true, diff.changed?(:at)
+    assert_equal false, diff.changed?([:quantity])
+    assert_equal false, diff.changed?(:quantity)
+
+    change = diff.changes_at(:at)
+    assert_kind_of TreeDiff::Change, change
+    assert_equal [:at], change.path
+    assert_equal Time.gm(2000, 1, 1, 12, 30), change.old
+    assert_equal Time.gm(2000, 1, 1, 1, 30), change.new
+
+    assert_nil diff.changes_at(:quantity)
   end
 
   def test_big_tree
@@ -68,7 +81,7 @@ class TreeDiffTest < Minitest::Test
 
   def test_polymorphic_path
     truck = Truck.new(number: 123, capacity: 55)
-    other_truck = Truck.new(number: 456, capacity: 25)
+    # other_truck = Truck.new(number: 456, capacity: 25)
     order = Order.create!(number: 'XYZ123', trucks: [truck])
 
     diff = OrderVehicleDiff.new(order)

data/tree_diff.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'tree_diff'
-  s.version     = '1.1.0'
+  s.version     = '1.1.1'
   s.date        = '2019-07-13'
   s.summary     = "Observe attribute changes in big complex object trees, like a generic & standalone ActiveModel::Dirty"
   s.description = "Given a tree of relationships in a similar format to strong params, analyzes attribute changes by " \

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tree_diff
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.1.1
 platform: ruby
 authors:
 - Michael Nelson
@@ -75,9 +75,13 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".ruby-version"
+- ".yardopts"
 - Gemfile
 - Gemfile.lock
 - LICENSE
+- README.md
+- Rakefile
+- bin/rake
 - lib/tree_diff.rb
 - test/helper.rb
 - test/tree_diff_test.rb