active_snapshot 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b48af4ad66af3d9fe9110f544df49f29ec6586969cb7e2c7f62431b54163a84
-  data.tar.gz: fddc58303f066d5b77b56304c4367874e2b3dda0ea2e76e710d81a0f1705861e
+  metadata.gz: d5fd89751eb3c64739f2a3242edfb4a8f3fd1dfce8047bbd4db51b790039ee39
+  data.tar.gz: 5cf804fd3bb81be067153fa1120b45f5045febf0eb93921950ae51bea17c65a8
 SHA512:
-  metadata.gz: 9a769fccb45b11f7163384b6ee79e5ff056b897cb3f382bb48054eaf9e20dba87371ab6b42da4ac117eafd136ebdc5d2dcd3441c7cf3a397ea087ec481dbc61d
-  data.tar.gz: 2ca41b8874d1511596e25893ddb9b0b05daeead16a12150ff25b1812b1dd3f2901fdcad501ece2681b4a96161e8909e5fd475d52e8c7eda72d74e83804b38574
+  metadata.gz: c079cdc615a35293cecbe0ab3c86df6a0b96e6bc0a1a92beb5b8580735d4a61209aa97623a18d9e06aeffeb109f94bbc742cea119e96421ba725ed9a22aae1eb
+  data.tar.gz: dad4d76b90fd8caa0dbd09a2c20d618bd6b8060de77eacbbad4eeda7d79cfa13be48fed5888f80122c607f8ce69acdf67eb7ce48707f54bd08dc3e8f9922604b

data/CHANGELOG.md

@@ -2,12 +2,26 @@ CHANGELOG
 ---------
 
 - **Unreleased**
-  * [View Diff](https://github.com/westonganger/active_snapshot/compare/v0.4.0...master)
+  * [View Diff](https://github.com/westonganger/active_snapshot/compare/v0.5.1...master)
   * Nothing yet
 
+- **v0.5.1** - Nov 11, 2024
+  * [View Diff](https://github.com/westonganger/active_snapshot/compare/v0.5.0...v0.5.1)
+  * [#66](https://github.com/westonganger/active_snapshot/pull/66) - Ensure `SnapshotItem#restore_item!` and `Snapshot#fetch_reified_items` bypass assignment for snapshot object data where the associated column no longer exists.
+  * [#63](https://github.com/westonganger/active_snapshot/pull/63) - Fix bug when enum value is nil
+
+- **v0.5.0** - Nov 8, 2024
+  * [View Diff](https://github.com/westonganger/active_snapshot/compare/v0.4.0...v0.5.0)
+  * [#61](https://github.com/westonganger/active_snapshot/pull/61) - Ensure snapshot record returned by `create_snapshot!` is `valid?`
+  * [#60](https://github.com/westonganger/active_snapshot/pull/60) - Store enum value as integer
+  * [#56](https://github.com/westonganger/active_snapshot/pull/56) - Add presence validation for object in SnapshotItem model
+  * [#57](https://github.com/westonganger/active_snapshot/pull/57) - Add readonly argument to `Shapshot#fetch_reified_items`
+  * [#53](https://github.com/westonganger/active_snapshot/pull/53) - Allow `ActiveSnapshot.config` to be called before ActiveRecord `on_load` hook has occurred
+  * [#52](https://github.com/westonganger/active_snapshot/pull/52) - Remove deprecated positional argument on `create_snapshot!`
+
 - **v0.4.0** - July 23, 2024
   * [View Diff](https://github.com/westonganger/active_snapshot/compare/v0.3.2...v0.4.0)
-  * [#44](https://github.com/westonganger/active_snapshot/pull/44) - Remove dependency on activerecord-import with vanilla ActiveRecord upsert_all
+  * [#44](https://github.com/westonganger/active_snapshot/pull/44) - Remove dependency on `activerecord-import` with vanilla ActiveRecord `upsert_all`
 
 - **v0.3.2** - Oct 17, 2023
   * [View Diff](https://github.com/westonganger/active_snapshot/compare/v0.3.1...v0.3.2)

data/README.md

@@ -9,15 +9,15 @@ Simplified snapshots and restoration for ActiveRecord models and associations wi
 Key Features:
 
 - Create and Restore snapshots of a parent record and any specified child records
-- Predictible and explicit behaviour provides much needed clarity to your restore logic
+- Predictable and explicit behaviour provides much needed clarity to your restore logic
 - Snapshots are created upon request only, we do not use any callbacks
 - Tiny method footprint so its easy to completely override the logic later
 
 Why This Library:
 
-Model Versioning and Restoration require concious thought, design, and understanding. You should understand your versioning and restoration process completely. This gem's small API and fully understandable design fully supports this.
+Model Versioning and Restoration require conscious thought, design, and understanding. You should understand your versioning and restoration process completely. This gem's small API and fully understandable design fully supports this.
 
-I do not recommend using paper_trail-association_tracking because it is mostly a blackbox solution which encourages you to set it up and then assume its Just Working<sup>TM</sup>. This makes for major data problems later. Dont fall into this trap. Instead read this gems brief source code completely before use OR copy the code straight into your codebase. Once you know it, then you are free.
+I do not recommend using [paper_trail-association_tracking](https://github.com/westonganger/paper_trail-association_tracking) because it is mostly a blackbox solution which encourages you to set it up and then assume its Just Working<sup>TM</sup>. This makes for major data problems later. Dont fall into this trap. Instead read this gems brief source code completely before use OR copy the code straight into your codebase. Once you know it, then you are free.
 
 
 
@@ -131,20 +131,67 @@ end
 
 Now when you run `create_snapshot!` the associations will be tracked accordingly
 
-# Reifying Snapshot Items
+# Reifying Snapshots
 
-You can view all of the reified snapshot items by calling the following method. Its completely up to you on how to use this data.
+A reified record refers to an ActiveRecord instance where the local objects data is set to match the snaphotted data, but the database remains changed.
+
+You can view all of the "reified" snapshot items by calling the following method. Its completely up to you on how to use this data.
 
 ```ruby
 reified_parent, reified_children_hash = snapshot.fetch_reified_items
 ```
 
-As a safety these records have the `@readonly = true` attribute set on them. If you want to perform any write actions on the returned instances you will have to set `@readonly = nil`.
+As a safety these records have the `readonly` attribute set on them.
+If you want to perform any write actions on the returned instances you will have to set the `readonly` attribute to `false`
 
 ```ruby
+reified_parent, reified_children_hash = snapshot.fetch_reified_items(readonly: false)
+# or
 reified_parent, reified_children_hash = snapshot.fetch_reified_items
+reified_children_hash.first.instance_variable_set("@readonly", false)
+```
+
+# Diffing Versions
+
+You can use the following example code to generate your own diffs.
+
+```ruby
+snapshot = post.snapshots.find_by!(identifier: "some-identifier")
+
+snapshot_item = snapshot.snapshot_items.find_by!(item_type: "Post")
+
+old_attrs = snapshot_item.object
+new_attrs = post.attributes # or could be another snapshot object
+
+attrs_not_changed = old_attrs.to_a.intersection(new_attrs.to_a).to_h
+
+attrs_changed = new_attrs.to_a - attrs_not_changed.to_a
+```
 
-reified_parent.instance_variable_set("@readonly", false)
+# Important Data Considerations / Warnings
+
+### Dropping columns
+
+If you plan to use the snapshot restore capabilities please be aware:
+
+Whenever you drop a database column and there already exists snapshots of that model then you are kind of silently breaking your restore mechanism. Because now the application will not be able to assign data to columns that dont exist on the model. We work around this by bypassing the attribute assignment for snapshot item object entries that does not correlate to a current database column.
+
+I recommend that you add an entry to this in your applications safe-migrations guidelines.
+
+If you would like to detect if this situation has already ocurred you can use the following script:
+
+```ruby
+SnapshotItem.all.each do |snapshot_item|
+  snapshot_item.object.keys.each do |key|
+    klass = Class.const_get(snapshot_item.item_type)
+
+    if !klass.column_names.include?(key)
+      invalid_data = snapshot_item.object.slice(*klass.column_names)
+
+      raise "invalid data found - #{invalid_data}"
+    end
+  end
+end
 ```
 
 # Key Models Provided & Additional Customizations

data/lib/active_snapshot/models/concerns/snapshots_concern.rb

@@ -8,13 +8,7 @@ module ActiveSnapshot
       has_many :snapshot_items, as: :item, class_name: 'ActiveSnapshot::SnapshotItem'
     end
 
-    def create_snapshot!(legacy_identifier=nil, identifier: nil, user: nil, metadata: nil)
-      if identifier.nil? && legacy_identifier
-        identifier = legacy_identifier
-
-        ActiveSupport::Deprecation.warn(LEGACY_POSITIONAL_ARGUMENT_WARNING)
-      end
-
+    def create_snapshot!(identifier: nil, user: nil, metadata: nil)
       snapshot = snapshots.create!({
         identifier: identifier,
         user_id: (user.id if user),
@@ -40,6 +34,8 @@ module ActiveSnapshot
 
       SnapshotItem.upsert_all(new_entries.map{|x| x.delete("id"); x }, returning: false)
 
+      snapshot.snapshot_items.reset # clear the association cache otherwise snapshot.valid? returns false
+
       snapshot
     end
 
@@ -127,7 +123,5 @@ module ActiveSnapshot
       end
     end
 
-    LEGACY_POSITIONAL_ARGUMENT_WARNING = "Supplying the snapshots :identifier as a positional argument is now deprecated and will be removed in upcoming versions. Please supply the snapshot identifier using the :identifier keyword argument instead.".freeze
-
   end
 end

data/lib/active_snapshot/models/snapshot.rb

@@ -46,8 +46,18 @@ module ActiveSnapshot
     end
 
     def build_snapshot_item(instance, child_group_name: nil)
+      attrs = instance.attributes
+
+      if instance.class.defined_enums.any?
+        instance.class.defined_enums.slice(*attrs.keys).each do |enum_col_name, enum_mapping|
+          val = attrs.fetch(enum_col_name)
+          next if val.nil?
+          attrs[enum_col_name] = enum_mapping.fetch(val)
+        end
+      end
+
       self.snapshot_items.new({
-        object: instance.attributes,
+        object: attrs,
         item_id: instance.id,
         item_type: instance.class.name,
         child_group_name: child_group_name,
@@ -96,15 +106,25 @@ module ActiveSnapshot
       return true
     end
 
-    def fetch_reified_items
+    def fetch_reified_items(readonly: true)
       reified_children_hash = {}.with_indifferent_access
 
       reified_parent = nil
 
       snapshot_items.each do |si|
-        reified_item = si.item_type.constantize.new(si.object)
+        reified_item = si.item_type.constantize.new
 
-        reified_item.readonly!
+        si.object.each do |k,v|
+          if reified_item.respond_to?("#{k}=")
+            reified_item[k] = v
+          else
+            # database column was likely dropped since the snapshot was created
+          end
+        end
+
+        if readonly
+          reified_item.readonly!
+        end
 
         key = si.child_group_name
 

data/lib/active_snapshot/models/snapshot_item.rb

@@ -12,22 +12,21 @@ module ActiveSnapshot
     validates :snapshot_id, presence: true
     validates :item_id, presence: true, uniqueness: { scope: [:snapshot_id, :item_type] }
     validates :item_type, presence: true
+    validates :object, presence: true
 
     def object
       return @object if @object
 
       if ActiveSnapshot.config.storage_method_json?
-        @object = JSON.parse(self[:object])
+        @object = self[:object] ? JSON.parse(self[:object]) : {}
       elsif ActiveSnapshot.config.storage_method_yaml?
-        yaml_method = "unsafe_load"
+        yaml_method = YAML.respond_to?(:unsafe_load) ? :unsafe_load : :load
 
-        if !YAML.respond_to?("unsafe_load")
-          yaml_method = "load"
-        end
-
-        @object = YAML.send(yaml_method, self[:object])
+        @object = self[:object] ? YAML.public_send(yaml_method, self[:object]) : {}
       elsif ActiveSnapshot.config.storage_method_native_json?
         @object = self[:object]
+      else
+        raise StandardError, "Unsupported storage_method: `#{ActiveSnapshot.config.storage_method}`"
       end
     end
 
@@ -52,7 +51,13 @@ module ActiveSnapshot
         self.item = item_klass.new
       end
 
-      item.assign_attributes(object)
+      object.each do |k,v|
+        if item.respond_to?("#{k}=")
+          item[k] = v
+        else
+          # database column was likely dropped since the snapshot was created
+        end
+      end
 
       item.save!(validate: false, touch: false)
     end

data/lib/active_snapshot/version.rb

@@ -1,3 +1,3 @@
 module ActiveSnapshot
-  VERSION = "0.4.0".freeze
+  VERSION = "0.5.1".freeze
 end

data/lib/active_snapshot.rb

@@ -3,27 +3,29 @@ require "active_snapshot/config"
 
 require 'active_support/lazy_load_hooks'
 
+module ActiveSnapshot
+  @@config = ActiveSnapshot::Config.new
+
+  def self.config(&block)
+    if block_given?
+      block.call(@@config)
+    else
+      return @@config
+    end
+  end
+end
+
 ActiveSupport.on_load(:active_record) do
   require "active_snapshot/models/snapshot"
   require "active_snapshot/models/snapshot_item"
 
   require "active_snapshot/models/concerns/snapshots_concern"
 
-  module ActiveSnapshot
+  ActiveSnapshot.module_eval do
     extend ActiveSupport::Concern
 
     included do
       include ActiveSnapshot::SnapshotsConcern
     end
-
-    @@config = ActiveSnapshot::Config.new
-
-    def self.config(&block)
-      if block_given?
-        block.call(@@config)
-      else
-        return @@config
-      end
-    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_snapshot
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Weston Ganger
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-07-23 00:00:00.000000000 Z
+date: 2024-11-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord