recorder 1.3.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2d2e570a4fef05c798efd2a10ded9db849f500e41fab1e13c6f9e485ebfdfdee
-  data.tar.gz: 3a3e7f23e99544e05e0e0008de975f9bea9ed2089de89d999ac601a80b3cbe11
+  metadata.gz: 064c2afab28615f3f268bfacee354fdf6fceff7063190e084783dfe1640fe054
+  data.tar.gz: 6062f268b4a47ea089cf90fac14ac124fc2c5e07f65be6d37228a663ec4cfc5e
 SHA512:
-  metadata.gz: 4202283d1af6b5da82c360a3537623516794855e56a31973ed43ff0f0bceb04cdfa412d180af0dab9dc30b096a5213966663dd0cb19af1130e76d52360c24570
-  data.tar.gz: 4b7451c330c0115755813f0736135b5323b5d1f72b0f0583e21e88dcc725f1adf6fd44c5ebc6fd6060046304c75be96e282ab590a01c0b47d65eb6d4edf8ca80
+  metadata.gz: ed30006c3d6f960d017a8b97853d5737624c9690f31ffc60ee3d0dc2dbbb21507f3e52e8203dd103192ba8648ca6dc643e969a232fd40a7ee65d0dcc7f11a87b
+  data.tar.gz: 689acc4c8867035e627413e5586280e2b05327efa7a002713903300016f19a99caa1194e172de45633f6b4fb8771cdf3a380905784f327b3df01bca39ed93129

data/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0]
+
+### Added
+
+- README coverage of what a revision's `data` holds: the complete attribute
+  snapshot on every event, when `changes` and `associations` are present, and
+  which events record a revision at all. No behaviour changes — the snapshot is
+  what the gem has always written, and it is now written down.
+- A known issue for the `changes` key on `destroy` revisions, which describes
+  the record's last update rather than the deletion.
+- A `changes:` option on `recorder` that merges extra entries into a revision's
+  `changes`. It takes a Proc evaluated on the record or the name of a method on it;
+  both receive the event.
+
+### Changed
+
+- `Recorder::Revision` declares both `belongs_to :user` and `belongs_to :item`
+  with `optional: true`. The associations have always been optional in practice,
+  but only because the gem is required before the Active Record railtie applies
+  `belongs_to_required_by_default`, so the reflections are built while the
+  default is still off. Had that ordering ever shifted, every revision without a
+  user would have failed validation, and so would every `destroy` revision,
+  which is written after its item's row is deleted. `Tape::Record#record` calls
+  `create`, not `create!`, so those revisions would have been dropped with
+  nothing raised anywhere. Recorded revisions are unchanged.
+
+### Fixed
+
+- `Recorder::Changeset#previous` and `#next` no longer raise `NoMethodError` when
+  the changes carry a key that is not an attribute of the model, and skip values
+  that are not a two-element `[old, new]` pair rather than indexing into them.
+
 ## [1.3.0] - 2026-09-16
 
 ### Added
@@ -104,7 +136,8 @@ Releases at and before 1.1.1 predate this changelog. See the
 [commit history](https://github.com/jetrockets/recorder/commits/master) for
 details.
 
-[Unreleased]: https://github.com/jetrockets/recorder/compare/v1.3.0...HEAD
+[Unreleased]: https://github.com/jetrockets/recorder/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/jetrockets/recorder/compare/v1.3.0...v1.4.0
 [1.3.0]: https://github.com/jetrockets/recorder/compare/v1.2.3...v1.3.0
 [1.2.3]: https://github.com/jetrockets/recorder/compare/v1.2.2...v1.2.3
 [1.2.2]: https://github.com/jetrockets/recorder/compare/v1.2.1...v1.2.2

data/README.md

@@ -73,10 +73,36 @@ Recorder supports the following options:
  * `only: [array]` - only these attributes are logged, other attributes are ingored;
  * `associations: {hash} (hash)` - allows to set what associations will be logged alongside with the model. For each association you can also set ignore and only options;
  * `async: bool` - a logging strategy (true - asynchronous, false - synchronous).
-
-These per-model options do not reach the recorder yet — see [Known issues](#known-issues).
+ * `changes: Proc | Symbol` - extra entries to merge into a revision's `changes`. A Proc
+   is evaluated on the record, a Symbol names a method on it; both receive the event
+   (`:create`, `:update` or `:destroy`) and return a hash of `name => [old, new]`, or
+   `nil` for nothing. Anything else raises `ArgumentError` where `recorder` is called.
+
+The entries are merged after `only:` and `ignore:` have been applied, so those
+filters never drop them, and a key that matches an attribute replaces that
+attribute's entry. An update that reports only custom entries still records a
+revision.
+
+Inside the callback, read `saved_changes` and `saved_change_to_<attribute>?`, not
+`<attribute>_changed?`: the callback runs from `after_create`/`after_update`, where
+the dirty state has already been reset.
+
+`Recorder::Changeset` rebuilds the previous and next versions by assigning each
+change onto a copy of the record, and skips what it cannot assign: a key that is
+not an attribute, and any value that is not a two-element `[old, new]` pair. To display such
+a key, define `previous_<key>`/`next_<key>` on the model's changeset class, and
+pick a name that `Recorder::Changeset` does not already answer to.
+
+These per-model options, `changes:` included, do not reach the recorder yet — see [Known issues](#known-issues).
 Until they do, every observed model records a full attribute snapshot, filtered
-only by the global `Recorder.config.ignore`.
+only by the global `Recorder.config.ignore`. Options declared as an instance
+method are read, so that is the way to opt into any of them today:
+
+```ruby
+def recorder_options
+  {ignore: %i[identifier], changes: :extra_changes}
+end
+```
 
 ### Global configuration
 
@@ -143,6 +169,26 @@ revision.user_id
 revision.action_date
 ```
 
+`data` carries a complete attribute snapshot on every event, not only what
+changed:
+
+- `attributes` — every attribute of the record as it stood when the callback
+  ran, filtered by the model's `only:` or `ignore:` and, failing those, by
+  `Recorder.config.ignore`. Always present.
+- `changes` — the same filter applied to `saved_changes`, as
+  `name => [old, new]`, plus any entries from `changes:`. Omitted when that
+  leaves nothing.
+- `associations` — those two keys again, one entry per association named in
+  `associations:`. Omitted when no association reports anything.
+
+The snapshot is the contract, not an accident of the implementation: a revision
+is self-contained, so reconstructing a record at a point in time does not mean
+replaying every prior diff. It is also what keeps a `destroy` revision useful,
+since the row it describes is gone.
+
+An `update` records a revision only when the record or one of its recorded
+associations reports a change; `create` and `destroy` always record one.
+
 `#item_changeset` wraps `data['changes']` in a `Recorder::Changeset`, which reads
 the values back as the model's own types:
 
@@ -170,7 +216,7 @@ as `"#{model}Changeset"` — or point at another one with a
 
 ## Known issues
 
-The gem is under active maintenance and these defects are known as of 1.2.3:
+The gem is under active maintenance and these defects are known as of 1.3.0:
 
 - The per-model options above (`ignore:`, `only:`, `associations:`, `async:`)
   are not applied. `Recorder::Tape` asks the record instance for
@@ -182,6 +228,10 @@ The gem is under active maintenance and these defects are known as of 1.2.3:
   `Recorder.store`, which `Recorder::Manager` drives.
 - Collection associations are never recorded. `associations:` handles only
   singular associations; a `has_many` reflection is skipped without a warning.
+- A `destroy` revision carries a `changes` key describing the record's last
+  *update*. `destroy` does not clear `saved_changes`, and `data` is built the
+  same way for every event. The `attributes` snapshot is the accurate record of
+  what was deleted.
 
 ## Development
 

data/lib/recorder/changeset.rb

@@ -33,7 +33,7 @@ module Recorder
       @previous_version = item.dup
 
       changes.each do |key, change|
-        @previous_version.send("#{key}=", change[0])
+        @previous_version.try("#{key}=", change[0]) if pair?(change)
       end
 
       @previous_version
@@ -49,10 +49,16 @@ module Recorder
       @next_version = item.dup
 
       changes.each do |key, change|
-        @next_version.send("#{key}=", change[1])
+        @next_version.try("#{key}=", change[1]) if pair?(change)
       end
 
       @next_version
     end
+
+    private
+
+    def pair?(change)
+      change.is_a?(Array) && change.size == 2
+    end
   end
 end

data/lib/recorder/observer.rb

@@ -27,6 +27,8 @@ module Recorder
       end
 
       def recorder(options = {})
+        Recorder::Tape::Data.validate_changes_option!(options[:changes])
+
         @recorder_options = options
 
         after_create do

data/lib/recorder/revision.rb

@@ -18,8 +18,8 @@ module Recorder
       )
     end
 
-    belongs_to :item, polymorphic: true, inverse_of: :revisions
-    belongs_to :user
+    belongs_to :item, polymorphic: true, inverse_of: :revisions, optional: true
+    belongs_to :user, optional: true
 
     validates :item_type, presence: true
     validates :event, presence: true

data/lib/recorder/tape/data.rb

@@ -23,8 +23,14 @@ module Recorder
         {attributes: sanitize_attributes(item.attributes, options)}
       end
 
+      def self.validate_changes_option!(callback)
+        return if callback.nil? || callback.is_a?(Proc) || callback.is_a?(Symbol) || callback.is_a?(String)
+
+        raise ArgumentError, "`changes:` expects a Proc or a method name, got #{callback.inspect}"
+      end
+
       def changes_for(event, options)
-        changes = sanitize_attributes(item.saved_changes, options)
+        changes = sanitize_attributes(item.saved_changes, options).merge(custom_changes_for(event, options))
 
         changes.present? ? {changes: changes} : {}
       end
@@ -37,6 +43,17 @@ module Recorder
 
       private
 
+      def custom_changes_for(event, options)
+        callback = options[:changes]
+        return {} unless callback
+
+        self.class.validate_changes_option!(callback)
+
+        changes = callback.is_a?(Proc) ? item.instance_exec(event, &callback) : item.send(callback, event)
+
+        changes ? Hash(changes).symbolize_keys : {}
+      end
+
       def sanitize_attributes(attributes, options)
         if options[:only].present?
           only = wrap_options(options[:only])

data/lib/recorder/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Recorder
-  VERSION = '1.3.0'
+  VERSION = '1.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: recorder
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Igor Alexandrov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-17 00:00:00.000000000 Z
+date: 2026-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord