rails_audit_log 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adf2bbd729f0c0a53c0016389d8b8af4ca66cedede3343bb3376cf880edc447c
-  data.tar.gz: 640764fdbe148a2f8d0309350ae74358256b7cc9b530f0c35d0bc045ef736b4c
+  metadata.gz: cb82307e35624fe226336c4fb33559b5432a6290c4978076aadec80e6939afa0
+  data.tar.gz: 47e700f38e3d1fbe2a0953ba687285389721b31e8a6531dcbc5e336c6d9af438
 SHA512:
-  metadata.gz: 938374f49a4385c038124abb6aeb95eaa8369dccc20d8eb125e96071954c3b8858cb22dc94781bdfa31e96d006645df5bb07f989c83d4ca35d1792451cb82f07
-  data.tar.gz: 82f6ca3524c11b954705d62b576d11c8ae5008f49b26c973789d43466a6d1ab3d4462fd012885a0b83177220c8ceda83c381af5db07e0b371deafca1db14badc
+  metadata.gz: 5dc66b780e8d1875260ef21c143b3ec823832ffa7e90c58f8392e002515d4cbe30c797936f4766bd15791a9b1b37e2f8918973f33fec58e396ca117a3623a563
+  data.tar.gz: d7fbf0c15e39d95a57270203b296ce5bac2835cc15f69d44cd6a7b000a884bc8d639cee91de5c1dd84aeaec64795fa6325397a1926a67f9a8317cc1128c18808

data/README.md

@@ -39,7 +39,7 @@ Every `create`, `update`, and `destroy` is now recorded automatically:
 
 ```ruby
 article = Article.create!(title: "Hello")
-article.audit_log_entries.count      # => 1
+article.audit_log_entries.count       # => 1
 article.audit_log_entries.first.event # => "create"
 
 article.update!(title: "World")
@@ -77,6 +77,123 @@ RailsAuditLog.with_actor(current_user) do
 end
 ```
 
+### Querying the audit log
+
+```ruby
+# Event scopes
+article.audit_log_entries.created_events
+article.audit_log_entries.updated_events
+article.audit_log_entries.destroyed_events
+
+# Filter by actor, resource, or time
+RailsAuditLog::AuditLogEntry.by_actor(current_user)
+RailsAuditLog::AuditLogEntry.for_resource(Article)
+RailsAuditLog::AuditLogEntry.for_resource(article)
+RailsAuditLog::AuditLogEntry.since(1.week.ago)
+RailsAuditLog::AuditLogEntry.until(Date.yesterday)
+
+# Find entries that touched a specific attribute
+RailsAuditLog::AuditLogEntry.touching(:title)
+
+# Inspect what changed
+entry = article.audit_log_entries.last
+entry.changed_attributes  # => ["title"]
+entry.diff
+# => { "title" => { from: "Hello", to: "World" } }
+```
+
+### Selective tracking
+
+Track only specific attributes, or exclude noisy ones:
+
+```ruby
+class Article < ApplicationRecord
+  include RailsAuditLog::Auditable
+
+  # Track only these columns
+  audit_log only: [:title, :status]
+
+  # Or exclude specific columns
+  audit_log ignore: [:cached_at, :views_count]
+end
+```
+
+Configure global defaults in an initializer:
+
+```ruby
+# config/initializers/rails_audit_log.rb
+RailsAuditLog.ignored_attributes = %w[updated_at cached_at]
+```
+
+Updates that produce no tracked changes after filtering are silently skipped.
+
+### Disabling auditing
+
+Suppress all audit writes inside a block — thread-safe, works in jobs and imports:
+
+```ruby
+RailsAuditLog.disable do
+  Article.insert_all!(bulk_rows)
+end
+
+RailsAuditLog.enabled? # => true (restored after the block)
+```
+
+Disable on a specific record instance:
+
+```ruby
+article.skip_audit_log { article.update!(cached_at: Time.current) }
+```
+
+### Object reconstruction
+
+#### Reify a single entry
+
+`AuditLogEntry#reify` returns an unsaved ActiveRecord instance reflecting the record's state **before** the entry was recorded:
+
+```ruby
+article.update!(title: "v2")
+entry = article.audit_log_entries.updated_events.last
+
+previous = entry.reify
+previous.title   # => "v1"  (the pre-update state)
+previous.persisted? # => false
+```
+
+Returns `nil` for `create` entries (nothing existed before).
+
+#### Reconstruct state at any point in time
+
+```ruby
+snapshot = RailsAuditLog.version_at(article, 1.week.ago)
+snapshot.title  # => whatever the title was a week ago
+```
+
+Returns `nil` if the record had no history at that time or was already destroyed.
+
+#### Navigate the version chain
+
+```ruby
+entry = article.audit_log_entries.updated_events.last
+entry.previous  # => the entry before this one
+entry.next      # => the entry after this one (nil if last)
+```
+
+### Object snapshot storage
+
+By default every entry stores a full `object` snapshot of the pre-change state alongside `object_changes`. This makes `reify` and `version_at` reliable without any database lookups:
+
+```ruby
+entry.object          # => { "id" => 1, "title" => "v1", ... }
+entry.object_changes  # => { "title" => ["v1", "v2"] }
+```
+
+To save storage at the cost of reduced reification accuracy, switch to diff-only mode:
+
+```ruby
+RailsAuditLog.store_snapshot = false
+```
+
 ## Requirements
 
 - Ruby >= 3.3

data/app/concerns/rails_audit_log/auditable.rb

@@ -30,19 +30,21 @@ module RailsAuditLog
     private
 
     def record_audit_create
-      record_audit_entry("create", saved_changes)
+      record_audit_entry("create", saved_changes, nil)
     end
 
     def record_audit_update
-      record_audit_entry("update", saved_changes)
+      snapshot = attributes.merge(saved_changes.transform_values { |v| v[0] }) if RailsAuditLog.store_snapshot
+      record_audit_entry("update", saved_changes, snapshot)
     end
 
     def record_audit_destroy
+      snapshot = attributes.dup if RailsAuditLog.store_snapshot
       changes = attributes.transform_values { |v| [v, nil] }
-      record_audit_entry("destroy", changes)
+      record_audit_entry("destroy", changes, snapshot)
     end
 
-    def record_audit_entry(event, changes)
+    def record_audit_entry(event, changes, snapshot = nil)
       return unless RailsAuditLog.enabled?
 
       filtered = filter_changes(changes)
@@ -54,6 +56,7 @@ module RailsAuditLog
         item_type:      self.class.name,
         item_id:        id,
         object_changes: filtered,
+        object:         snapshot,
         actor_type:     actor&.class&.name,
         actor_id:       actor.respond_to?(:id) ? actor.id : nil
       )

data/app/models/rails_audit_log/audit_log_entry.rb

@@ -38,6 +38,40 @@ module RailsAuditLog
 
     # Instance methods
 
+    def reify
+      return nil if event == "create"
+
+      klass = item_type.constantize
+
+      if object.present?
+        instance = klass.new
+        instance.assign_attributes(object.except("id"))
+        instance.id = object.fetch("id") { item_id }
+        return instance
+      end
+
+      # Fallback: diff-only mode or entries recorded before snapshot support
+      from_attrs = (object_changes || {}).transform_values { |from_to| from_to[0] }
+
+      if event == "update"
+        record = klass.find_by(id: item_id)
+        from_attrs = record.attributes.merge(from_attrs) if record
+      end
+
+      instance = klass.new
+      instance.assign_attributes(from_attrs.except("id"))
+      instance.id = from_attrs.fetch("id") { item_id }
+      instance
+    end
+
+    def previous
+      self.class.where(item_type: item_type, item_id: item_id).where("id < ?", id).order(id: :desc).first
+    end
+
+    def next
+      self.class.where(item_type: item_type, item_id: item_id).where("id > ?", id).order(id: :asc).first
+    end
+
     def changed_attributes
       object_changes&.keys || []
     end
@@ -48,11 +82,11 @@ module RailsAuditLog
       object_changes.transform_values { |from_to| { from: from_to[0], to: from_to[1] } }
     end
 
-    # Attribute scope — uses json_extract (SQLite/MySQL) or json ? key (PostgreSQL)
+    # Attribute scope — uses json_extract (SQLite/MySQL) or ->> (PostgreSQL)
     scope :touching, ->(attribute) {
       if connection.adapter_name =~ /PostgreSQL/i
         # :nocov:
-        where("object_changes ? :key", key: attribute.to_s)
+        where("object_changes->>? IS NOT NULL", attribute.to_s)
         # :nocov:
       else
         where("json_extract(object_changes, ?) IS NOT NULL", "$.#{attribute}")

data/lib/generators/rails_audit_log/install/templates/create_audit_log_entries.rb

@@ -5,6 +5,7 @@ class CreateAuditLogEntries < ActiveRecord::Migration[<%= ActiveRecord::Migratio
       t.string  :item_type,  null: false
       t.bigint  :item_id,    null: false
       t.json    :object_changes
+      t.json    :object
       t.string  :actor_type
       t.bigint  :actor_id
       t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }

data/lib/rails_audit_log/version.rb

@@ -1,3 +1,3 @@
 module RailsAuditLog
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/rails_audit_log.rb

@@ -5,6 +5,7 @@ module RailsAuditLog
   # Global default columns to ignore across all audited models.
   # Override in an initializer: RailsAuditLog.ignored_attributes = %w[updated_at cached_at]
   mattr_accessor :ignored_attributes, default: %w[updated_at]
+  mattr_accessor :store_snapshot, default: true
 
   def self.actor
     Thread.current[:rails_audit_log_actor]
@@ -33,4 +34,23 @@ module RailsAuditLog
   ensure
     Thread.current[:rails_audit_log_disabled] = previous
   end
+
+  def self.version_at(record, time)
+    entry = AuditLogEntry
+      .where(item_type: record.class.name, item_id: record.id)
+      .where(created_at: ..time)
+      .order(created_at: :desc, id: :desc)
+      .first
+
+    return nil if entry.nil? || entry.event == "destroy"
+
+    klass = record.class
+    to_attrs = (entry.object_changes || {}).transform_values { |v| v[1] }
+    attrs = entry.object.present? ? entry.object.merge(to_attrs) : to_attrs
+
+    instance = klass.new
+    instance.assign_attributes(attrs.except("id"))
+    instance.id = attrs.fetch("id") { entry.item_id }
+    instance
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_audit_log
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chuck Smith