culturecode-track_changes 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfa353667777cba682df7ab603e3b4b21054439c6f6d91e4c0a0a719a244de33
-  data.tar.gz: 1155b70851fddaa85d6c10e7c0e9541649117ed8a9cf6dd38550788559269093
+  metadata.gz: 0c9bb5bdbc7a137501b16be9525858c58cd8665a673f0d81616e7ea08bda7c5b
+  data.tar.gz: 6b1b61340da3ca8e3af00f43cb8b4ed8fb634a03a5111301e9d30501258bccad
 SHA512:
-  metadata.gz: 0e9f8c86da3f47175fd32bdefc8b070f2526dea41fcc279f5a4e4392dd464eec3d4ca68b2f2b9fd9d785c87c47e110d50463f382875cfd360e9ee3a222c603e7
-  data.tar.gz: 2cb9c5348ac4a7d6f24c1c3bbd0f1eed42098d5d361009d8ec2d5a820863dba06ea2f2333db2cb61a015f7c90d593cf821dae14cd477ac03eaf6ffcbc926153f
+  metadata.gz: 458e536d0b57c406cc66b150b5be511a086aaf5b1fc6aad7e282d0aeb1d8bd4cfb1ce1296820ccfaf03098c25b6d38d6d8ddd4dbfce3195160c803666cd4b3da
+  data.tar.gz: da6901abda1bd01c87b01b0f7cc00be43226f0f7e29a1d480790542930d6a95e86d8a7d76b5a7c0d07839e79217d29a1eb9660318de29fbaf7f840775ec0d55f

data/README.md

@@ -24,6 +24,13 @@ class CreateTrackChangesTables < ActiveRecord::Migration
 end
 ```
 
+## Configuration
+
+```ruby
+TrackChanges::Configuration.cascade_destroy = false # Controls whether tracked changes are deleted when the record is deleted. Can be set to false if an audit trail of destroyed records is desired. Default: true
+TrackChanges::Configuration.serialize = false # Controls whether tracked changes are serialized as YAML before being written to the database. Can be set to false if the `state`, `from`, and `to` columns are JSON datatype instead of text. Default: true
+```
+
 ## Usage
 
 ```ruby
@@ -32,6 +39,11 @@ class Person < ActiveRecord::Base
 end
 ```
 
+```ruby
+Person.snapshot_all # Initialize snapshots for existing records so the next time the record is saved a diff can be generated.
+Person.tracked_change(status: "approved", assigned_to: "user_123") # Returns a list of diffs where specific attributes changed to the specified values.
+```
+
 ### Options
 By default all model attributes are tracked, except the primary_key, usually ```id```, ```created_at```, and ```updated_at```.
 
@@ -40,6 +52,8 @@ By default all model attributes are tracked, except the primary_key, usually ```
 - ```:methods``` accepts a field name or array of field names to track in addition to the default fields
 - ```:track_timestamps``` accepts a boolean, enabling or disabling tracking of ```created_at``` and ```updated_at```
 - ```:track_primary_key``` accepts a boolean, enabling or disabling tracking of the model's primary key
+- ```:track_locking_column``` accepts a boolean, enabling or disabling tracking of the model's locking column
+
 
 ### Attribution
 Changes can be attributed to a particular source. The source is saved as a string

data/app/helpers/track_changes/diff_helper.rb

@@ -29,12 +29,14 @@ module TrackChanges
 
       if record = diff.record
         field_name = diff.record.class.human_attribute_name(field)
-        reflection = diff.record.class.reflections.values.detect {|reflection| reflection.foreign_key == field.to_s }
+        reflection = diff.record.class.reflect_on_association(field) # Look up association by name, e.g. users for has_many :users
+        reflection ||= diff.record.class.reflections.values.detect {|ref| ref.foreign_key == field.to_s } # Detect association by foreign key, e.g. user_id for belongs_to :user
       end
 
       if reflection
-        from = reflection.klass.find_by_id(from) || content_tag(:span, 'DELETED', :class => 'deleted', :title => "This #{field_name} has been deleted") if from.present?
-        to   = reflection.klass.find_by_id(to)   || content_tag(:span, 'DELETED', :class => 'deleted', :title => "This #{field_name} has been deleted") if to.present?
+        primary_key = reflection.options.fetch(:primary_key, :id)
+        from = reflection.klass.where(primary_key => from) || content_tag(:span, 'DELETED', :class => 'deleted', :title => "This #{field_name} has been deleted") if from.present?
+        to   = reflection.klass.where(primary_key => to)   || content_tag(:span, 'DELETED', :class => 'deleted', :title => "This #{field_name} has been deleted") if to.present?
       end
 
       if from.blank?
@@ -48,8 +50,8 @@ module TrackChanges
 
     def link_diff_field_value(value, link_models = [])
       case value
-      when Array
-        value.collect{|v| link_diff_field_value(v, link_models) }.to_sentence.html_safe
+      when Array, ActiveRecord::Relation
+        safe_join(value.collect {|v| link_diff_field_value(v, link_models) }, ', ')
       when *link_models
         link_to(value.to_s, value)
       else

data/app/models/track_changes/diff.rb

@@ -4,8 +4,10 @@ module TrackChanges
 
     belongs_to :record, :polymorphic => true
 
-    serialize :from, Hash
-    serialize :to, Hash
+    if Configuration.serialize
+      serialize :from, Hash
+      serialize :to, Hash
+    end
 
     # Returns changes but only those where the string representation of the value has changed
     def visible_changes

data/app/models/track_changes/snapshot.rb

@@ -4,13 +4,26 @@ module TrackChanges
 
     belongs_to :record, :polymorphic => true
 
-    serialize :state, Hash
+    serialize :state, Hash if Configuration.serialize
 
     before_save :capture_record_state
 
     # Returns a hash of the current values for all tracked fields on the record
     def self.record_state(record)
-      Hash[record.class.track_changes_fields.collect {|method_name| [method_name, record.send(method_name)] }]
+      Hash[record.class.track_changes_fields.collect {|method_name| [method_name, dump_attribute_value(record.send(method_name))]   }]
+    end
+
+    def self.dump_attribute_value(value)
+      case value
+      when ActiveRecord::Relation
+        dump_attribute_value(value.to_a).sort
+      when Array
+        value.map {|member| dump_attribute_value(member) }
+      when ActiveRecord::Base
+        value.send(value.class.primary_key)
+      else
+        value
+      end
     end
 
     # Creates a diff object that shows the changes between this snapshot and the record's state
@@ -21,7 +34,7 @@ module TrackChanges
       to             = {}
 
       record.class.track_changes_fields.each do |key|
-        if snapshot_state.key?(key) && snapshot_state[key] != record_state[key]
+        if snapshot_state.key?(key) && snapshot_state[key] != record_state[key] # We check for the existence of the key in the snapshot before recording so we don't declare newly tracked attributes as "changed" on their first time recorded
           from[key] = snapshot_state[key]
           to[key] = record_state[key]
         end

data/lib/track_changes/configuration.rb

@@ -0,0 +1,6 @@
+module TrackChanges
+  module Configuration
+    mattr_accessor :cascade_destroy, :default => true # Destroy tracked changes when record is destroyed?
+    mattr_accessor :serialize, :default => true # Serialize data in ruby before writing to the database. Not necessary if the diff and snapshot data columns are JSON.
+  end
+end

data/lib/track_changes/engine.rb

@@ -1,3 +1,4 @@
+require 'track_changes/configuration'
 require 'track_changes/model'
 require 'track_changes/controller'
 require 'track_changes/attribution'

data/lib/track_changes/model.rb

@@ -11,8 +11,10 @@ module TrackChanges
         attr_accessor :track_changes # Faux attribute to allow disabling of change tracking on this record
         attr_writer   :track_changes_by # Faux attribute to store who made the changes so we can save it in the diff
 
-        has_one :snapshot, :as => :record, :class_name => 'TrackChanges::Snapshot' # A representation of this record as it was last saved
-        has_many :diffs, lambda { reorder('id DESC') }, :as => :record, :class_name => 'TrackChanges::Diff' # A representation of changes made between saves through this record's lifetime
+        # A representation of this record as it was last saved
+        has_one :snapshot, :as => :record, :class_name => 'TrackChanges::Snapshot', :dependent => Configuration.cascade_destroy ? :destroy : nil
+        # A representation of changes made between saves through this record's lifetime
+        has_many :diffs, lambda { reorder('id DESC') }, :as => :record, :class_name => 'TrackChanges::Diff', :dependent => Configuration.cascade_destroy ? :delete_all : nil
 
         after_save :persist_tracked_changes
       end
@@ -21,11 +23,18 @@ module TrackChanges
     module ClassMethods
       # Returns the method names to call to fetch the fields tracked for changes
       def track_changes_fields
-        fields =  Array(track_changes_options[:only]).collect(&:to_s).presence || self.attribute_names
+        fields =  Array(track_changes_options[:only]).collect(&:to_s).presence || default_track_changes_fields
         fields -= Array(track_changes_options[:except]).collect(&:to_s)
         fields += Array(track_changes_options[:methods]).collect(&:to_s)
         fields -= ['created_at', 'updated_at'] unless track_changes_options[:track_timestamps]
         fields -= [primary_key] unless track_changes_options[:track_primary_key]
+        fields -= [locking_column] unless track_changes_options[:track_locking_column]
+
+        return fields.uniq
+      end
+
+      def default_track_changes_fields
+        attribute_names - stored_attributes.keys.map(&:to_s) + stored_attributes.values.flatten.map(&:to_s)
       end
 
       # Create snapshots for all records so that the next changes made are captured
@@ -36,11 +45,18 @@ module TrackChanges
         # Create new snapshots
         where.not(:id => joins(:snapshot)).find_each(&:create_snapshot)
       end
+
+      # Record a diff and update the snapshot for all records in the scope
+      # This can be used to record a diff after an `update_all`.
+      def persist_tracked_changes(track_changes_by: nil)
+        find_each do |record|
+          record.track_changes_by = track_changes_by
+          record.persist_tracked_changes
+        end
+      end
     end
 
     module InstanceMethods
-      private
-
       def track_changes_by
         @track_changes_by || TrackChanges.default_attribution
       end
@@ -49,7 +65,7 @@ module TrackChanges
       def persist_tracked_changes
         return if track_changes == false
 
-        new_record = id_was.blank?
+        new_record = was_new_record_before_save?
         action     = new_record ? 'create' : 'update'
         changes_by = track_changes_by.is_a?(ActiveRecord::Base) ? track_changes_by.id : track_changes_by
 
@@ -64,6 +80,37 @@ module TrackChanges
           snapshot.create_diff(:action => action, :changes_by => changes_by, :from => {})
         end
       end
+
+      def was_new_record_before_save?
+        if !respond_to?(:attribute_before_last_save) # Rails < 6
+          id_was.blank?
+        elsif saved_change_to_attribute?(:id) # Rails <=5
+          attribute_before_last_save(:id).blank?
+        else # Allow this method to be used outside of a transaction, e.g. after a bulk update
+          new_record?
+        end
+      end
+
+      # Filters tracked change diffs to only those where the given attributes changed *to* the specified values.
+      #
+      # It builds a scope that matches records where each given attribute in `to` has the specified value.
+      #
+      # Example:
+      #   model.tracked_change(status: "approved", priority: "high")
+      #   # => returns diffs where status became "approved" and priority became "high"
+      #
+      # Params:
+      # - changes (keyword arguments): One or more attribute-value pairs to match against the `to` column.
+      #
+      # Returns:
+      # - ActiveRecord::Relation: A filtered scope on the diffs table.
+      def tracked_change(**changes)
+        table_name = diffs.quoted_table_name
+        column_name = diffs.connection.quote_column_name(:to)
+        changes.reduce(diffs) do |scope, (attribute, value)|
+          scope.where("#{table_name}.#{column_name} ->> ? = ?", attribute, value)
+        end
+      end
     end
   end
 end

data/lib/track_changes/version.rb

@@ -1,3 +1,3 @@
 module TrackChanges
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: culturecode-track_changes
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nicholas Jakobsen, Ryan Wallace
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-20 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -56,6 +55,7 @@ files:
 - lib/tasks/track_changes_tasks.rake
 - lib/track_changes.rb
 - lib/track_changes/attribution.rb
+- lib/track_changes/configuration.rb
 - lib/track_changes/controller.rb
 - lib/track_changes/engine.rb
 - lib/track_changes/model.rb
@@ -64,7 +64,6 @@ homepage: https://github.com/culturecode/track_changes
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -79,9 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.9
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Easily track changes to various ActiveRecord models
 test_files: []