paper_trail_diff 0.15.0 → 0.17.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +724 -1
- data/README.md +43 -8
- data/docs/architecture.md +7 -5
- data/docs/performance.md +89 -32
- data/docs/reference.md +427 -96
- data/docs/testing.md +260 -32
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
- data/lib/paper_trail_diff/activity_boundary.rb +55 -34
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
- data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
- data/lib/paper_trail_diff/activity_event.rb +33 -21
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
- data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
- data/lib/paper_trail_diff/activity_history.rb +90 -49
- data/lib/paper_trail_diff/activity_range.rb +9 -35
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
- data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
- data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
- data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
- data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
- data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
- data/lib/paper_trail_diff/activity_view.rb +22 -11
- data/lib/paper_trail_diff/analysis.rb +39 -6
- data/lib/paper_trail_diff/analysis_batch.rb +16 -58
- data/lib/paper_trail_diff/approximate_paths.rb +4 -8
- data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
- data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
- data/lib/paper_trail_diff/association_discovery.rb +1 -6
- data/lib/paper_trail_diff/association_key.rb +9 -6
- data/lib/paper_trail_diff/association_traversal.rb +49 -6
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
- data/lib/paper_trail_diff/batch_preload.rb +2 -12
- data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
- data/lib/paper_trail_diff/change_attribution.rb +314 -0
- data/lib/paper_trail_diff/change_row.rb +30 -10
- data/lib/paper_trail_diff/comparison_batch.rb +3 -4
- data/lib/paper_trail_diff/configuration.rb +1 -1
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
- data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
- data/lib/paper_trail_diff/deprecation.rb +4 -43
- data/lib/paper_trail_diff/diagnostics.rb +8 -7
- data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
- data/lib/paper_trail_diff/endpoint.rb +78 -44
- data/lib/paper_trail_diff/errors.rb +2 -9
- data/lib/paper_trail_diff/fallback_paths.rb +2 -5
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
- data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
- data/lib/paper_trail_diff/historical_filter.rb +40 -15
- data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
- data/lib/paper_trail_diff/instrumentation.rb +0 -8
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
- data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
- data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
- data/lib/paper_trail_diff/nested_comparator.rb +46 -19
- data/lib/paper_trail_diff/net_change.rb +276 -0
- data/lib/paper_trail_diff/own_window.rb +35 -0
- data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
- data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
- data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
- data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
- data/lib/paper_trail_diff/prepared_history.rb +31 -36
- data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
- data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
- data/lib/paper_trail_diff/read_snapshot.rb +99 -0
- data/lib/paper_trail_diff/recorded_changes.rb +10 -11
- data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
- data/lib/paper_trail_diff/recorded_class.rb +14 -19
- data/lib/paper_trail_diff/recorded_columns.rb +33 -0
- data/lib/paper_trail_diff/root_version_plan.rb +20 -22
- data/lib/paper_trail_diff/root_version_selection.rb +39 -29
- data/lib/paper_trail_diff/scope_condition.rb +92 -32
- data/lib/paper_trail_diff/scope_ranking.rb +27 -34
- data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
- data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
- data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
- data/lib/paper_trail_diff/stored_json_values.rb +52 -0
- data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
- data/lib/paper_trail_diff/stored_values.rb +20 -0
- data/lib/paper_trail_diff/support.rb +185 -35
- data/lib/paper_trail_diff/time_of_day.rb +39 -0
- data/lib/paper_trail_diff/time_range.rb +40 -22
- data/lib/paper_trail_diff/time_version_range.rb +5 -10
- data/lib/paper_trail_diff/timeline_builder.rb +9 -3
- data/lib/paper_trail_diff/timeline_range.rb +18 -12
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
- data/lib/paper_trail_diff/total_order.rb +55 -0
- data/lib/paper_trail_diff/transaction_cut.rb +235 -75
- data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
- data/lib/paper_trail_diff/value_objects.rb +8 -4
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
- data/lib/paper_trail_diff/version_boundary.rb +41 -23
- data/lib/paper_trail_diff/version_query.rb +25 -25
- data/lib/paper_trail_diff/version_range.rb +12 -16
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
- data/lib/paper_trail_diff/version_table.rb +12 -8
- data/lib/paper_trail_diff.rb +32 -44
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
- data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
- data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
- data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
- data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
- data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
- data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
- data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
- data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
- data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
- data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
- data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
- data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
- data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
- data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
- data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
- data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
- data/sig/generated/paper_trail_diff/errors.rbs +2 -11
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
- data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
- data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
- data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
- data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
- data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
- data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
- data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
- data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
- data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
- data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
- data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
- data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
- data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
- data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
- data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
- data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
- data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
- data/sig/generated/paper_trail_diff/support.rbs +120 -23
- data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
- data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
- data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
- data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
- data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
- data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
- data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
- data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
- data/sig/generated/paper_trail_diff.rbs +16 -16
- metadata +31 -7
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
data/docs/reference.md
CHANGED
|
@@ -76,9 +76,16 @@ Six things follow from this:
|
|
|
76
76
|
changes the values the record's next version stores, or its current row. The
|
|
77
77
|
gem reads the result of a change from there, so the write appears in the step
|
|
78
78
|
for that record's previous recorded change and is attributed to its author.
|
|
79
|
-
Ending a range at a version leaves out only the writes after it.
|
|
79
|
+
Ending a range at a version leaves out only the writes after it. A column
|
|
80
|
+
that `has_paper_trail only:` or `ignore:` leaves out of `object_changes` is
|
|
81
|
+
read the same way, so a key saved with a version is that version's change.
|
|
82
|
+
Rails updates `counter_cache` columns like this, so a parent's count changes
|
|
83
|
+
in the step of the parent's previous change; pass the column in `ignore:` to
|
|
84
|
+
leave it out.
|
|
80
85
|
[`recorded_changes`](#what-a-version-recorded) reads what a version itself
|
|
81
86
|
recorded, and activity steps can [include it](#what-each-event-recorded-recorded_changes-true).
|
|
87
|
+
With it, [change rows](#change-rows) give such a write a row of its own,
|
|
88
|
+
credited to no one.
|
|
82
89
|
- **A record created without a version looks as if it always existed.** A
|
|
83
90
|
row written with versioning off, or imported with `insert_all`, has no
|
|
84
91
|
`create` version, so history never reports it as added: its earliest
|
|
@@ -136,8 +143,9 @@ PaperTrailDiff.timeline(article, within: 1.week.ago..Time.current)
|
|
|
136
143
|
|
|
137
144
|
- `from:` defaults to `:first`, the record's earliest version.
|
|
138
145
|
- `to:` defaults to the record itself, meaning its current state. Pass a
|
|
139
|
-
version instead
|
|
140
|
-
again
|
|
146
|
+
version instead to anchor the result there. It does not change when the
|
|
147
|
+
record is edited again, unless a transaction that stamped changes before that
|
|
148
|
+
version commits after it; see [version order](#version-order).
|
|
141
149
|
- A version stands for the state before its transaction, since PT-AT rebuilds
|
|
142
150
|
associations as they were before it. Child changes saved in the same
|
|
143
151
|
transaction, such as the update behind a `touch: true` parent version, fall
|
|
@@ -166,14 +174,60 @@ all of today and `august...september` stops before September 1. A string is a
|
|
|
166
174
|
time in `Time.zone` unless it names an offset. Without `Time.zone`, both are
|
|
167
175
|
read in UTC, never in the server's own zone.
|
|
168
176
|
|
|
177
|
+
An endless range, such as `1.day.ago..`, runs through the current saved state:
|
|
178
|
+
it holds every version saved since it began, whatever time its server's clock
|
|
179
|
+
gave it, and it ends at the current record. `report` uses one.
|
|
180
|
+
|
|
169
181
|
A window edge that falls inside a transaction moves back to where that
|
|
170
182
|
transaction began, so the whole transaction is in the later window, as it is
|
|
171
|
-
when a range [starts or ends at a version](#choosing-a-range).
|
|
172
|
-
|
|
173
|
-
and the `touch: true` article version saved with it
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
183
|
+
when a range [starts or ends at a version](#choosing-a-range). It moves when
|
|
184
|
+
the transaction saved the root record after the edge, such as a comment edit
|
|
185
|
+
and the `touch: true` article version saved with it, or saved the root before
|
|
186
|
+
the edge and a record of a class on the requested paths after it. A
|
|
187
|
+
transaction that saved the root only before the edge, and nothing on its paths
|
|
188
|
+
after it, moves no edge: the root's change is in the earlier window, with its
|
|
189
|
+
version, even when the transaction went on to save another article. A
|
|
190
|
+
transaction that saved only associated records moves no edge either. When it
|
|
191
|
+
saved some of them before the edge and some after, its changes are still all
|
|
192
|
+
in one window: in the later one when a version it saved after the edge is of a
|
|
193
|
+
record on the requested paths before or after the transaction, and otherwise
|
|
194
|
+
in the earlier one. A polymorphic `belongs_to` names its target's class only in
|
|
195
|
+
each record, so a target saved after the edge moves nothing: the root's change
|
|
196
|
+
is then in the earlier window and the target's in the later one. A
|
|
197
|
+
[transaction group](#one-step-per-transaction-group-transaction) lists in
|
|
198
|
+
`sources` only the versions inside its window. So back-to-back windows, or a
|
|
199
|
+
`report` with `since:` after an earlier report, show each change exactly
|
|
200
|
+
once, credited to the transaction that made it. Each root moves its own
|
|
201
|
+
edges, so in a batch two roots can start a few moments apart.
|
|
202
|
+
|
|
203
|
+
`analysis.window` is the window an `Analysis` covers after any such move, as a
|
|
204
|
+
Ruby range, endless for `report` and any other endless window. It is `nil` when
|
|
205
|
+
`within:` or `since:` was not given. Every step of the analysis is inside it,
|
|
206
|
+
so to check a step against the window, use `analysis.window` rather than the
|
|
207
|
+
range you passed: a step at the start of a moved window begins before the time
|
|
208
|
+
you asked for.
|
|
209
|
+
|
|
210
|
+
```ruby
|
|
211
|
+
analysis = PaperTrailDiff.analyze_many(articles, within: window, activity: true).values.first
|
|
212
|
+
analysis.window # => window, or one that starts earlier
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
Each move emits a `moved_window.paper_trail_diff` notification whose payload
|
|
216
|
+
has `item_type`, `item_id`, the `requested` range, and the moved `window`. In
|
|
217
|
+
history saved by your application, an edge moves back by the time one
|
|
218
|
+
transaction took, usually well under a second. A move of minutes or days
|
|
219
|
+
means a transaction ran that long, or that the versions' times were changed
|
|
220
|
+
after they were saved, as a test might do; see
|
|
221
|
+
[writing history in tests](#writing-history-in-tests).
|
|
222
|
+
|
|
223
|
+
A closed window can still change. PaperTrail stamps a version's `created_at`
|
|
224
|
+
when it builds the version, inside its transaction, and the transaction commits
|
|
225
|
+
later. A transaction that stamped a change inside the window and committed
|
|
226
|
+
after the window was read adds that change to it. Wait longer than your longest
|
|
227
|
+
transaction after the window ends before you rely on it, so that every
|
|
228
|
+
transaction that could have written in the window has committed. A report
|
|
229
|
+
through now is final only for changes older than that delay. The gem cannot see
|
|
230
|
+
open transactions, so it cannot tell when a window has settled.
|
|
177
231
|
|
|
178
232
|
To show what the window's last change produced, the gem reads the state just
|
|
179
233
|
before the next change after the window:
|
|
@@ -197,19 +251,14 @@ in the step for that record's last recorded change.
|
|
|
197
251
|
If the window's last change destroyed the record, the window closes on that
|
|
198
252
|
deletion instead. See [a destroyed record](#a-destroyed-record).
|
|
199
253
|
|
|
200
|
-
`close_on: :current` is deprecated and has no effect; passing it warns through
|
|
201
|
-
`PaperTrailDiff.deprecator`. Remove it. In a Rails app, register the deprecator
|
|
202
|
-
with `Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`
|
|
203
|
-
to handle its warnings as the app's own.
|
|
204
|
-
|
|
205
254
|
`timeline` returns no steps for a window with no versions of the root record.
|
|
206
255
|
`activity_timeline` still reports chosen associations that changed in such a
|
|
207
256
|
window.
|
|
208
257
|
|
|
209
258
|
### Reporting only some changes: `version_scope:`
|
|
210
259
|
|
|
211
|
-
`version_scope:` narrows which
|
|
212
|
-
|
|
260
|
+
`version_scope:` narrows which changes are reported. It receives the version
|
|
261
|
+
relation and returns a narrower one:
|
|
213
262
|
|
|
214
263
|
```ruby
|
|
215
264
|
user_edits = ->(scope) { scope.where.not(whodunnit: nil) }
|
|
@@ -218,7 +267,7 @@ PaperTrailDiff.timeline(article, within: window, version_scope: user_edits)
|
|
|
218
267
|
```
|
|
219
268
|
|
|
220
269
|
It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
|
|
221
|
-
and `
|
|
270
|
+
`analyze_scope`, and `report`.
|
|
222
271
|
|
|
223
272
|
- Each reported change is compared with the version right after it, even if
|
|
224
273
|
that version is filtered out. So each step shows exactly what that one change
|
|
@@ -229,12 +278,29 @@ and `analyze_scope`.
|
|
|
229
278
|
reported alice: what alice changed bob: what bob changed
|
|
230
279
|
```
|
|
231
280
|
|
|
232
|
-
-
|
|
233
|
-
has
|
|
234
|
-
|
|
235
|
-
- `activity_timeline`
|
|
236
|
-
|
|
237
|
-
|
|
281
|
+
- `timeline` looks at the root record's versions only, so someone who only
|
|
282
|
+
edited comments has none for it to report. Activity reports their changes:
|
|
283
|
+
see [one person's changes](#one-persons-changes).
|
|
284
|
+
- In activity (`activity_timeline`, `activity: true`, and `report`), it
|
|
285
|
+
chooses the changes on the requested associations as well. A transaction is
|
|
286
|
+
reported whole, every step of it, when the filter keeps any version saved
|
|
287
|
+
in it, of whichever record: PT-AT shows a transaction's changes together, at
|
|
288
|
+
its last step, so no step inside one belongs to a single version. A version
|
|
289
|
+
saved outside a transaction is reported when the filter keeps it. Every
|
|
290
|
+
version is still read, so each step shows what its own change did, and an
|
|
291
|
+
analysis starts at the first change the filter keeps and ends after the
|
|
292
|
+
last. Without associations, the steps are the root's versions the filter
|
|
293
|
+
keeps, as `timeline` reports them.
|
|
294
|
+
- In `analyze_scope` and `report`, it also chooses which records are selected:
|
|
295
|
+
a record is selected only when the filter keeps one of its own versions in
|
|
296
|
+
the window, or a version of a record on a requested association. A record
|
|
297
|
+
changed only by versions it drops would have nothing to report, so it is
|
|
298
|
+
left out, and it does not count toward `limit:`.
|
|
299
|
+
- The record and its requested associations keep their versions in one table
|
|
300
|
+
(see [custom version classes](#models-schemas-and-edge-cases)), and the
|
|
301
|
+
filter reads it for all of them. A condition on `item_type` or `item_id`
|
|
302
|
+
therefore leaves out the associations' changes; filter on the version's own
|
|
303
|
+
columns, such as `whodunnit` or `event`.
|
|
238
304
|
|
|
239
305
|
## compare
|
|
240
306
|
|
|
@@ -275,8 +341,7 @@ diff.to_h
|
|
|
275
341
|
- A current record must be saved, not destroyed, and have no unsaved changes.
|
|
276
342
|
The gem reloads it, so in-memory edits and cached associations are ignored.
|
|
277
343
|
- Options: `associations:`, `ignore:`, and `allow_approximate:` (see
|
|
278
|
-
[costly associations](#costly-associations)).
|
|
279
|
-
deprecated (see [reusing loaded records](#reusing-loaded-records)).
|
|
344
|
+
[costly associations](#costly-associations)).
|
|
280
345
|
|
|
281
346
|
## compare_many
|
|
282
347
|
|
|
@@ -306,21 +371,6 @@ diffs.fetch(["Order", orders.first.id.to_s]) # => PaperTrailDiff::Diff
|
|
|
306
371
|
If you look up versions yourself, do it in bulk. Looking up one record at a
|
|
307
372
|
time brings back the per-record queries this method avoids.
|
|
308
373
|
|
|
309
|
-
### Reusing loaded records
|
|
310
|
-
|
|
311
|
-
Every method reloads the current records it compares with, together with the
|
|
312
|
-
requested associations, in a query for the records and one per association
|
|
313
|
-
level. `reload_live_endpoints: false` on `compare`, `compare_many`, and
|
|
314
|
-
`activity_timeline` skips that reload and reads your loaded objects instead.
|
|
315
|
-
It is deprecated and will be removed: it saves those few queries per call (2
|
|
316
|
-
for 500 articles with their comments), and the values then come from objects
|
|
317
|
-
that may be stale. Until it is removed it still works,
|
|
318
|
-
with a warning. A requested association that is not loaded raises
|
|
319
|
-
`UnloadedAssociationError`, and one with a `limit` or `offset`, directly or in
|
|
320
|
-
a part it goes through, or a scope that takes the owner, is read again for
|
|
321
|
-
each record, because Active Record's `preload` applies a limit to all the
|
|
322
|
-
records it loads together.
|
|
323
|
-
|
|
324
374
|
## timeline
|
|
325
375
|
|
|
326
376
|
`timeline(record)` returns one step for each pair of neighboring versions of the
|
|
@@ -390,12 +440,26 @@ end
|
|
|
390
440
|
current record. You do not need to save the article after each comment change.
|
|
391
441
|
- Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`,
|
|
392
442
|
`version_scope:`, `snapshots:`, `group:`, `recorded_changes:`,
|
|
393
|
-
`allow_approximate:`.
|
|
394
|
-
[reusing loaded records](#reusing-loaded-records)).
|
|
443
|
+
`allow_approximate:`.
|
|
395
444
|
|
|
396
445
|
### One person's changes
|
|
397
446
|
|
|
398
|
-
|
|
447
|
+
Pass a [`version_scope:`](#reporting-only-some-changes-version_scope) that
|
|
448
|
+
keeps their versions. Activity then reports only the transactions they saved
|
|
449
|
+
a version in, on the record or on its associations:
|
|
450
|
+
|
|
451
|
+
<!-- executable:readme-person-scope -->
|
|
452
|
+
```ruby
|
|
453
|
+
priya = ->(versions) { versions.where(whodunnit: "Priya Shah") }
|
|
454
|
+
steps = PaperTrailDiff.activity_timeline(
|
|
455
|
+
article, within: window, associations: %i[comments tags], version_scope: priya
|
|
456
|
+
)
|
|
457
|
+
|
|
458
|
+
steps.map { |step| step.source_boundary.whodunnit }.uniq # ["Priya Shah"]
|
|
459
|
+
```
|
|
460
|
+
|
|
461
|
+
To count everyone's changes from one read, group the steps in Ruby by
|
|
462
|
+
`source_boundary.whodunnit` instead:
|
|
399
463
|
|
|
400
464
|
<!-- executable:readme-person-changes -->
|
|
401
465
|
```ruby
|
|
@@ -413,13 +477,9 @@ authors = attributed.group_by { |step| step.source_boundary.whodunnit }
|
|
|
413
477
|
.transform_values(&:length)
|
|
414
478
|
```
|
|
415
479
|
|
|
416
|
-
This includes changes to associations, which `version_scope:` cannot see.
|
|
417
|
-
Filter after the call rather than asking the gem for fewer versions: every step
|
|
418
|
-
has to be rebuilt anyway for each one to be correct, so filtering earlier saves
|
|
419
|
-
nothing.
|
|
420
|
-
|
|
421
480
|
For many records, use `report` or `analyze_many(..., activity: true)` instead of
|
|
422
|
-
calling `activity_timeline` in a loop, so the database work is shared.
|
|
481
|
+
calling `activity_timeline` in a loop, so the database work is shared. With
|
|
482
|
+
`version_scope:`, `report` selects only the records that person changed.
|
|
423
483
|
|
|
424
484
|
### One step per transaction: `group: :transaction`
|
|
425
485
|
|
|
@@ -435,9 +495,22 @@ PaperTrailDiff.activity_timeline(article, associations: [:comments], group: :tra
|
|
|
435
495
|
it. A field set and then restored inside the transaction is not reported.
|
|
436
496
|
- Its `source_boundary` is the first event in the transaction. That event's
|
|
437
497
|
author is not necessarily the author of every grouped change. `step.sources`
|
|
438
|
-
lists every event in the transaction, each with its own author, except
|
|
439
|
-
those of records
|
|
498
|
+
lists every event in the transaction, each with its own author, except two
|
|
499
|
+
kinds: those of records outside the tree before the transaction, after it,
|
|
500
|
+
and at every version of the root it saved; and those saved before a window
|
|
501
|
+
that starts inside a transaction of associated records only (see
|
|
502
|
+
[time windows](#time-windows)). Its [change rows](#change-rows) each name
|
|
503
|
+
the event of their own record.
|
|
440
504
|
- Versions without a `transaction_id` are never grouped.
|
|
505
|
+
- A savepoint that rolls back can split one transaction into more than one
|
|
506
|
+
group. PT-AT clears the transaction id when the savepoint rolls back, so the
|
|
507
|
+
versions the transaction saves afterwards form a separate group. Releasing
|
|
508
|
+
the savepoint keeps one group.
|
|
509
|
+
- A step joins only the group of the step just before it. Two transactions
|
|
510
|
+
that save in the same tree at the same time, so that their versions
|
|
511
|
+
interleave, each form a group for every run of their own versions: the
|
|
512
|
+
state between two runs holds the other transaction's change, so no single
|
|
513
|
+
step could show either one alone.
|
|
441
514
|
- Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
|
|
442
515
|
`activity: true`, and by `report`.
|
|
443
516
|
|
|
@@ -466,6 +539,7 @@ step.from_snapshot.associations["comments"].records.first.attributes["author"]
|
|
|
466
539
|
record did not exist yet.
|
|
467
540
|
- Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
|
|
468
541
|
`activity: true`, and by `report`.
|
|
542
|
+
- [`net_changes`](#net-changes) reads them, so it needs this option.
|
|
469
543
|
|
|
470
544
|
### What each event recorded: `recorded_changes: true`
|
|
471
545
|
|
|
@@ -495,10 +569,11 @@ end
|
|
|
495
569
|
- Each boundary's `recorded_changes` is what
|
|
496
570
|
`PaperTrailDiff.recorded_changes(version)` returns for its version: `nil`
|
|
497
571
|
when nothing was recorded, and always `nil` for the current record. The
|
|
498
|
-
versions are already loaded, so this adds no queries
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
572
|
+
versions are already loaded, so this adds no queries. A version's changes
|
|
573
|
+
are decoded the first time a boundary's `recorded_changes` is read, and once
|
|
574
|
+
for the whole call, however many steps or records share the version. Read
|
|
575
|
+
them from the boundary rather than calling `PaperTrailDiff.recorded_changes`
|
|
576
|
+
for its version, which decodes it again each time.
|
|
502
577
|
- Without the option, `recorded_changes` raises `ConfigurationError` instead of
|
|
503
578
|
returning `nil`, so a missing option cannot look like a version that recorded
|
|
504
579
|
nothing.
|
|
@@ -577,10 +652,23 @@ analysis.timeline # the same steps timeline returns
|
|
|
577
652
|
analysis.activity_timeline # nil unless activity: true
|
|
578
653
|
analysis.from_snapshot # the full state at the start (nil before creation)
|
|
579
654
|
analysis.to_snapshot # the full state at the end
|
|
655
|
+
analysis.window # the time window it covers, or nil without within:
|
|
580
656
|
analysis.to_h(snapshots: true, metadata: true)
|
|
581
657
|
```
|
|
582
658
|
|
|
583
659
|
- It accepts the same ranges as `timeline`.
|
|
660
|
+
- `from_snapshot` is the record as it was when the range began: before the
|
|
661
|
+
first change in a window, or before the change of the version you passed as
|
|
662
|
+
`from:`. With `version_scope:`, a window begins at the first change the
|
|
663
|
+
filter keeps, on the record or, with `activity: true`, on its associations.
|
|
664
|
+
It is `nil` when the record was created inside the range; the state right
|
|
665
|
+
after it was created is then the first activity step's `to_snapshot`, which
|
|
666
|
+
`snapshots: true` keeps.
|
|
667
|
+
- To read the record at one version, with its values typed and its
|
|
668
|
+
associations, take `from_snapshot` from a range that starts there:
|
|
669
|
+
`PaperTrailDiff.analyze(article, from: version, to: article).from_snapshot`.
|
|
670
|
+
Don't decode `version.object` yourself; the gem casts what PaperTrail
|
|
671
|
+
stores, which a `json` column or an enum leaves in another form.
|
|
584
672
|
- When nothing in the range is reported, the analysis is empty: an empty
|
|
585
673
|
`diff` and timelines, and `nil` for `from_snapshot` and `to_snapshot`. Here
|
|
586
674
|
`nil` means no state was read, not that the record did not exist; reading
|
|
@@ -640,7 +728,11 @@ report.roots # the selected records, in relation order
|
|
|
640
728
|
report.unreachable # identities of selected records that no longer exist
|
|
641
729
|
report.deleted # { identity => Analysis or nil }, with include_deleted: true
|
|
642
730
|
|
|
643
|
-
|
|
731
|
+
report.roots.each do |order|
|
|
732
|
+
report.analysis_for(order) # its Analysis, without building the identity
|
|
733
|
+
end
|
|
734
|
+
|
|
735
|
+
analyses, unreachable = report # destructures into analyses and unreachable
|
|
644
736
|
```
|
|
645
737
|
|
|
646
738
|
It takes the same options as `analyze_many`, plus `limit:`, `historical_filter:`,
|
|
@@ -649,15 +741,14 @@ all history.
|
|
|
649
741
|
|
|
650
742
|
### report
|
|
651
743
|
|
|
652
|
-
`report(scope, since:, limit:)` is `analyze_scope` with
|
|
653
|
-
|
|
654
|
-
recently":
|
|
744
|
+
`report(scope, since:, limit:)` is `analyze_scope` with `within: since..`, an
|
|
745
|
+
endless window, and `activity: true`. Use it for "what happened recently":
|
|
655
746
|
|
|
656
747
|
```ruby
|
|
657
748
|
report = PaperTrailDiff.report(Article.all, since: 1.day.ago, limit: 100)
|
|
658
749
|
```
|
|
659
750
|
|
|
660
|
-
It accepts `associations:`, `ignore:`, `snapshots:`, `group:`,
|
|
751
|
+
It accepts `associations:`, `ignore:`, `version_scope:`, `snapshots:`, `group:`,
|
|
661
752
|
`recorded_changes:`, `include_deleted:`, `historical_filter:`, `max_filter_versions:`,
|
|
662
753
|
and `allow_approximate:`.
|
|
663
754
|
|
|
@@ -670,7 +761,9 @@ and `allow_approximate:`.
|
|
|
670
761
|
both. Nested paths count at every level, and a `has_many :through` counts its
|
|
671
762
|
join rows too. Without `activity: true`, an analysis compares a record's own
|
|
672
763
|
versions and cannot show a change to its associations alone, so only a
|
|
673
|
-
record's own version selects it.
|
|
764
|
+
record's own version selects it. With
|
|
765
|
+
[`version_scope:`](#reporting-only-some-changes-version_scope), only the
|
|
766
|
+
versions the filter keeps select it, the record's own and its associations'.
|
|
674
767
|
- **An analysis can still be empty.** A record is selected by any version on its
|
|
675
768
|
paths, but its analysis compares only the state you requested. A join row
|
|
676
769
|
whose role changed, or a version that touched only ignored columns, selects a
|
|
@@ -682,9 +775,17 @@ and `allow_approximate:`.
|
|
|
682
775
|
selected, the call raises `BatchLimitExceededError` instead of returning part
|
|
683
776
|
of the answer. Narrow the relation or the window, or raise the limit.
|
|
684
777
|
- **To paginate, use the relation.** Its `order`, `limit`, and `offset` choose
|
|
685
|
-
the page. Without an `order`, records are taken in ascending ID order.
|
|
686
|
-
|
|
687
|
-
|
|
778
|
+
the page. Without an `order`, records are taken in ascending ID order. Any
|
|
779
|
+
other order gets the ID as a last tie-breaker unless it already sorts by it,
|
|
780
|
+
so that records that tie are neither skipped nor read twice. SQL text counts
|
|
781
|
+
as sorting by the ID when it names the column, alone or after the table's
|
|
782
|
+
name, as `order("title, id")` does. Give the queries that show the page the
|
|
783
|
+
same tie-breaker, such as `order(:status, :id)`, so that they list the
|
|
784
|
+
records the report analyzed. If a join repeats a record, it is analyzed
|
|
785
|
+
once, in order of first appearance. A relation grouped by anything but the
|
|
786
|
+
ID, such as `select("MAX(id) AS id").group(:author_id)`, keeps its own
|
|
787
|
+
order, since a database sorts groups only by what they group or aggregate.
|
|
788
|
+
It needs one that tells its groups apart, such as `order(:author_id)`.
|
|
688
789
|
- Selection still scans the versions in the window, so keep windows reasonable
|
|
689
790
|
for large tables. Each requested association adds one query per level, however
|
|
690
791
|
many records it selects. Changes to associations are found from PT-AT's
|
|
@@ -695,19 +796,22 @@ and `allow_approximate:`.
|
|
|
695
796
|
|
|
696
797
|
A relation's conditions read the table, and a deleted record has no row.
|
|
697
798
|
Records that changed in the window but no longer exist are listed in
|
|
698
|
-
`unreachable`, including those selected by a change to their associations
|
|
699
|
-
|
|
700
|
-
|
|
799
|
+
`unreachable`, including those selected by a change to their associations,
|
|
800
|
+
when the state each held when it was destroyed meets the relation's
|
|
801
|
+
conditions. That test needs conditions it can read, as `include_deleted:`
|
|
802
|
+
below does; for any other relation, such as one with SQL text or a join,
|
|
803
|
+
`unreachable` lists every such record of the model, whatever the relation. It
|
|
804
|
+
is not paginated.
|
|
701
805
|
|
|
702
806
|
`include_deleted: true` tests each of them against the relation's conditions,
|
|
703
|
-
as it stood when it was destroyed, and keeps only those that match. So a
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
here, since they choose a page of existing rows. A record whose
|
|
710
|
-
PaperTrail did not record has no state to test and stays listed.
|
|
807
|
+
as it stood when it was destroyed, and keeps only those that match. So a report
|
|
808
|
+
on `Article.where(account_id: account.id)` returns that account's deletions,
|
|
809
|
+
not every account's. The relation's conditions must be plain conditions on the
|
|
810
|
+
model's own columns, as a [readable association scope's](#costly-associations)
|
|
811
|
+
must, ranges included; anything else, such as a join or SQL text, raises
|
|
812
|
+
`ConfigurationError`. `Article.none` keeps none. Its order, limit, and offset
|
|
813
|
+
are ignored here, since they choose a page of existing rows. A record whose
|
|
814
|
+
destroy PaperTrail did not record has no state to test and stays listed.
|
|
711
815
|
|
|
712
816
|
It then analyzes the kept records from their `destroy` versions and returns the
|
|
713
817
|
results in `deleted`, keyed the same way. A value is `nil` when no `destroy`
|
|
@@ -737,8 +841,11 @@ report = PaperTrailDiff.report(
|
|
|
737
841
|
)
|
|
738
842
|
```
|
|
739
843
|
|
|
740
|
-
The filter checks the record as it was when
|
|
741
|
-
change made inside it.
|
|
844
|
+
The filter checks the record as it was when its window started and after each
|
|
845
|
+
change made inside it. That window is the one its analysis covers
|
|
846
|
+
(`analysis.window`): a transaction that crosses an edge moves the edge to where
|
|
847
|
+
the transaction began (see [time windows](#time-windows)). A record matches if
|
|
848
|
+
any of those states match. With a
|
|
742
849
|
hash, every key must be equal (`==`) once both sides are cast to the
|
|
743
850
|
attribute's type, as `where` casts its values: `{ status: :published }` matches
|
|
744
851
|
an enum, and a date or time matches whether the history stored it as YAML or
|
|
@@ -791,6 +898,11 @@ MySQL and SQL Server compare strings without regard to case or trailing spaces
|
|
|
791
898
|
by default, which the gem cannot repeat, and neither is PostgreSQL's
|
|
792
899
|
`citext`.
|
|
793
900
|
|
|
901
|
+
Ranges, such as `where(position: 2..)` or `where(created_at: 1.day.ago...)`,
|
|
902
|
+
and Arel's `gt`, `gteq`, `lt`, and `lteq`, are read on the columns an order
|
|
903
|
+
can sort by, below: integer, integer enum, date, and datetime columns, with
|
|
904
|
+
the same conditions on a datetime's precision.
|
|
905
|
+
|
|
794
906
|
A `limit` or `offset`, and the order of a `has_one`, are read the same way
|
|
795
907
|
when the order is total and the gem can repeat it:
|
|
796
908
|
|
|
@@ -827,12 +939,12 @@ join records fills two places, as in the query. A `has_one :through` whose
|
|
|
827
939
|
own scope or whose parts have a limit, an offset, or a `has_one` order is not
|
|
828
940
|
read.
|
|
829
941
|
|
|
830
|
-
The gem cannot read the rest: a `limit` or `offset` whose order is not total
|
|
831
|
-
|
|
942
|
+
The gem cannot read the rest: a `limit` or `offset` whose order is not total or
|
|
943
|
+
sorts by another column type (strings follow a collation) or by a datetime
|
|
832
944
|
history cannot rank exactly, scopes that take the owner
|
|
833
|
-
(`->(article) { ... }`), scopes written as SQL strings
|
|
834
|
-
join or select, and conditions on other column types or
|
|
835
|
-
a string column on MySQL. For these it asks PT-AT, which costs queries per
|
|
945
|
+
(`->(article) { ... }`), scopes written as SQL strings, ranges on other column
|
|
946
|
+
types, scopes that join or select, and conditions on other column types or
|
|
947
|
+
other tables, such as a string column on MySQL. For these it asks PT-AT, which costs queries per
|
|
836
948
|
record and is approximate: PT-AT rebuilds an association from its current
|
|
837
949
|
members, swapping in their older versions, and never checks the scope against
|
|
838
950
|
them. A record that entered the scope since is reported as a member it was
|
|
@@ -844,7 +956,7 @@ such a path and names it. Remove it from `associations:`, rewrite its scope as
|
|
|
844
956
|
plain conditions on the target's own columns, or pass `allow_approximate:
|
|
845
957
|
true` to accept PT-AT's answer, which also accepts its cost of queries per
|
|
846
958
|
record in batch methods. A comparison of two current records reads no history
|
|
847
|
-
and needs no opt-in.
|
|
959
|
+
and needs no opt-in.
|
|
848
960
|
|
|
849
961
|
A polymorphic `belongs_to` is loaded together too, with one query per target
|
|
850
962
|
class. Its classes are known only from the records, though, so batch methods
|
|
@@ -989,8 +1101,10 @@ another record with the same HABTM also saved a version (see the
|
|
|
989
1101
|
is when saved, including a member attached or created earlier in the same
|
|
990
1102
|
transaction. A change it captures is credited to the step before it, so its
|
|
991
1103
|
author is whoever saved the version before the checkpoint, unless that is a
|
|
992
|
-
checkpoint the same person saved just before the change.
|
|
993
|
-
|
|
1104
|
+
checkpoint the same person saved just before the change. A member created in
|
|
1105
|
+
the checkpoint's transaction is reported in the step of its creation instead,
|
|
1106
|
+
or, when the range ends at the checkpoint, in the step before it. Don't save
|
|
1107
|
+
the instance that made the HABTM change again; it records the old membership.
|
|
994
1108
|
|
|
995
1109
|
### Files from ActiveStorage
|
|
996
1110
|
|
|
@@ -1086,6 +1200,7 @@ for numeric IDs).
|
|
|
1086
1200
|
| `ActivityStep` | one `activity_timeline` step |
|
|
1087
1201
|
| `ActivityBoundary` | one end of a step |
|
|
1088
1202
|
| `ChangeRow` | one row from `change_rows` |
|
|
1203
|
+
| `NetChange` | one record's entry from `net_changes` |
|
|
1089
1204
|
| `Analysis` | result of `analyze` |
|
|
1090
1205
|
| `ScopedAnalysis` | result of `analyze_scope` and `report` |
|
|
1091
1206
|
| `TraversalEntry`, `RecordReference` | entries from `each_change` and `each_entry` |
|
|
@@ -1138,7 +1253,7 @@ record reachable through two requested paths appears at both.
|
|
|
1138
1253
|
### Change rows
|
|
1139
1254
|
|
|
1140
1255
|
For a table or an export, `change_rows` flattens activity into one row per
|
|
1141
|
-
change, each
|
|
1256
|
+
change, each credited to the version that made it:
|
|
1142
1257
|
|
|
1143
1258
|
```ruby
|
|
1144
1259
|
steps.last.change_rows # one activity step
|
|
@@ -1152,14 +1267,15 @@ row.from # nil for :added
|
|
|
1152
1267
|
row.to # nil for :removed
|
|
1153
1268
|
row.record # a RecordReference, or nil for the root
|
|
1154
1269
|
row.association_path # ["comments"], or [] for the root
|
|
1155
|
-
row.source # the
|
|
1270
|
+
row.source # the ActivityBoundary of the version that made the change
|
|
1271
|
+
row.unversioned? # true for a change saved without a version
|
|
1156
1272
|
row.to_h # the above, plus version_id, event, whodunnit, recorded_at,
|
|
1157
1273
|
# and transaction_id
|
|
1158
1274
|
```
|
|
1159
1275
|
|
|
1160
1276
|
- An edited field is one `:changed` row. A record that appeared or disappeared
|
|
1161
1277
|
gets an `:added` or `:removed` row with `attribute` `nil`, then a row for each
|
|
1162
|
-
field that
|
|
1278
|
+
field that is not `nil` and for each record it holds.
|
|
1163
1279
|
- A replaced `belongs_to` or `has_one` target gives the old record `:removed`
|
|
1164
1280
|
rows, then the new one `:added` rows.
|
|
1165
1281
|
- Rows follow the diff's walking order, and an analysis's rows follow its steps
|
|
@@ -1167,6 +1283,112 @@ row.to_h # the above, plus version_id, event, whodunnit, recorded_at
|
|
|
1167
1283
|
- `Analysis#change_rows` raises `ConfigurationError` without `activity: true`.
|
|
1168
1284
|
`report.change_rows` leaves out a deleted record without destroy history.
|
|
1169
1285
|
|
|
1286
|
+
Which version a row names:
|
|
1287
|
+
|
|
1288
|
+
- A field's change names the version of the row's own record that made it,
|
|
1289
|
+
among those its step's transaction saved. Inside a transaction, a record's
|
|
1290
|
+
change can show up at a later event than its own, in a step another record's
|
|
1291
|
+
version opens; the row still names its own record's version. With
|
|
1292
|
+
`recorded_changes: true`, that is the version that recorded the field's new
|
|
1293
|
+
value. Without it, the gem cannot tell which of a record's versions made
|
|
1294
|
+
the change, so the row names the last of them.
|
|
1295
|
+
- A record created or destroyed names its `create` or `destroy`. Its fields
|
|
1296
|
+
name the version that recorded each value: the `create`, or a later save in
|
|
1297
|
+
the same step. A record that joined or left through another record's
|
|
1298
|
+
change, such as a new `belongs_to` target or a `has_and_belongs_to_many`
|
|
1299
|
+
member, names the step's `source_boundary`.
|
|
1300
|
+
|
|
1301
|
+
With `recorded_changes: true`, a change PaperTrail did not record gets a row of
|
|
1302
|
+
its own: a write [saved without a version](#how-papertrail-stores-history),
|
|
1303
|
+
such as `update_columns`. Its source has kind `:unversioned` and names the
|
|
1304
|
+
record, with no version, event, author, or time, so `to_h` has `nil` for
|
|
1305
|
+
`version_id`, `event`, `whodunnit`, `recorded_at`, and `transaction_id`. A
|
|
1306
|
+
field a version recorded changing from `10` to `20`, and that a later
|
|
1307
|
+
`update_columns` set to `99`, gives two rows: `10` to `20`, credited to the
|
|
1308
|
+
version, then `20` to `99`, unversioned. To report only what versions
|
|
1309
|
+
recorded, leave such rows out:
|
|
1310
|
+
|
|
1311
|
+
<!-- executable:reference-unversioned-rows -->
|
|
1312
|
+
```ruby
|
|
1313
|
+
analysis = PaperTrailDiff.analyze(
|
|
1314
|
+
article, associations: [:comments], activity: true, recorded_changes: true
|
|
1315
|
+
)
|
|
1316
|
+
|
|
1317
|
+
analysis.change_rows.reject(&:unversioned?)
|
|
1318
|
+
```
|
|
1319
|
+
|
|
1320
|
+
The gem splits off only what the versions show was not recorded. A row stays
|
|
1321
|
+
whole, credited to a version, where they cannot:
|
|
1322
|
+
|
|
1323
|
+
- the version recorded no changes, as a `touch` does, or the version table
|
|
1324
|
+
has no `object_changes` column;
|
|
1325
|
+
- the column is one `has_paper_trail ignore:` or `skip:` names, or `only:`
|
|
1326
|
+
leaves out;
|
|
1327
|
+
- the field is one a `create` left at its default, which no version records:
|
|
1328
|
+
a later write to it reads as the value the record was created with;
|
|
1329
|
+
- the version is in a transaction that began before a window and saved no
|
|
1330
|
+
version of the root (see [time windows](#time-windows)), whose earlier
|
|
1331
|
+
versions the window does not read.
|
|
1332
|
+
|
|
1333
|
+
Rows follow each step's diff, so a change a version recorded and a later write
|
|
1334
|
+
without a version undid, leaving the field as it was, has no row.
|
|
1335
|
+
|
|
1336
|
+
### Net changes
|
|
1337
|
+
|
|
1338
|
+
`net_changes` folds change rows into one entry per record: its fields before
|
|
1339
|
+
the rows a block keeps, and its fields with only their changes made. This
|
|
1340
|
+
example keeps the rows with an author. A write saved without a version has
|
|
1341
|
+
none, so with `recorded_changes: true` it is left out:
|
|
1342
|
+
|
|
1343
|
+
<!-- executable:reference-net-changes -->
|
|
1344
|
+
```ruby
|
|
1345
|
+
analysis = PaperTrailDiff.analyze(
|
|
1346
|
+
article, associations: [:comments], activity: true, snapshots: true,
|
|
1347
|
+
recorded_changes: true
|
|
1348
|
+
)
|
|
1349
|
+
|
|
1350
|
+
changes = analysis.net_changes { |row| row.source.whodunnit }
|
|
1351
|
+
```
|
|
1352
|
+
|
|
1353
|
+
```ruby
|
|
1354
|
+
change = changes.first
|
|
1355
|
+
change.root? # true for the article, which comes first
|
|
1356
|
+
change.record # a RecordReference, or nil for the root
|
|
1357
|
+
change.association_path # ["comments"], or [] for the root
|
|
1358
|
+
change.before # a RecordSnapshot of its fields, or nil if it was added
|
|
1359
|
+
change.after # its fields after the kept changes, or nil if removed
|
|
1360
|
+
change.diff # a Diff of before and after
|
|
1361
|
+
change.added? # before is nil
|
|
1362
|
+
change.removed? # after is nil
|
|
1363
|
+
change.sources # the ActivityBoundary of each kept change, each once
|
|
1364
|
+
report.net_changes { |row| ... } # { identity => changes }, keyed as change_rows
|
|
1365
|
+
```
|
|
1366
|
+
|
|
1367
|
+
Without a block, every row is kept, and `before` and `after` are the record's
|
|
1368
|
+
states around all of its changes.
|
|
1369
|
+
|
|
1370
|
+
- `before` is the record's state when the step holding its first kept change
|
|
1371
|
+
began, so it includes the changes dropped before then.
|
|
1372
|
+
- `after` is `before` with only the kept changes made: each field takes the
|
|
1373
|
+
value of its last kept row. A record that appears takes the fields it
|
|
1374
|
+
appeared with. A record appears or disappears only through its own row,
|
|
1375
|
+
whose `attribute` is `nil`, so a block that keeps only some fields also
|
|
1376
|
+
leaves out the records added and removed.
|
|
1377
|
+
- A record whose kept changes leave it as it was is left out, as is one added
|
|
1378
|
+
and removed again.
|
|
1379
|
+
- The root comes first whenever anything is listed. When only the records it
|
|
1380
|
+
holds changed, its `before` and `after` are the same and its `diff` is
|
|
1381
|
+
empty.
|
|
1382
|
+
- `before` and `after` hold only the record's own fields; each record it holds
|
|
1383
|
+
has an entry of its own. A record has one entry for each association path,
|
|
1384
|
+
whichever records along the path hold it, so a reply moved from one comment
|
|
1385
|
+
to another is one entry.
|
|
1386
|
+
- The states come from the steps' snapshots, so `net_changes` raises
|
|
1387
|
+
`ConfigurationError` without `snapshots: true`, as it does without
|
|
1388
|
+
`activity: true`.
|
|
1389
|
+
- To leave out only the writes saved without a version, keep the other rows:
|
|
1390
|
+
`{ |row| !row.unversioned? }`.
|
|
1391
|
+
|
|
1170
1392
|
## JSON columns
|
|
1171
1393
|
|
|
1172
1394
|
A `json` or `jsonb` column is compared as one value. `nested_changes` reports
|
|
@@ -1181,6 +1403,8 @@ PaperTrailDiff.nested_changes(from_value, to_value) # also accepts two values
|
|
|
1181
1403
|
```
|
|
1182
1404
|
|
|
1183
1405
|
- Paths are arrays because a key may contain a dot.
|
|
1406
|
+
- `:a` and `"a"` are one key at any depth, inside arrays too, so a path's keys
|
|
1407
|
+
are strings. Values are reported as they were given.
|
|
1184
1408
|
- Arrays are compared by their elements, not positions. An `ArrayChange` has
|
|
1185
1409
|
`added`, `removed`, and `reordered?`, plus the whole `from` and `to`. Objects
|
|
1186
1410
|
inside arrays are compared whole.
|
|
@@ -1228,6 +1452,10 @@ Other details:
|
|
|
1228
1452
|
- Unlike PaperTrail's `version.changeset`, it never loads the record. That
|
|
1229
1453
|
saves a query per version, and a deleted record's values keep their types,
|
|
1230
1454
|
such as an enum's label rather than the integer PaperTrail stored.
|
|
1455
|
+
- Values read as a step's `diff` reads them, so a recorded value equals the
|
|
1456
|
+
state it produced: a time of day falls on 2000-01-01, and with
|
|
1457
|
+
[JSON history](#history-stored-as-json), times keep the digits history
|
|
1458
|
+
stores and binary and `serialize`d values read as JSON stored them.
|
|
1231
1459
|
|
|
1232
1460
|
For activity steps, pass `recorded_changes: true` instead of loading the
|
|
1233
1461
|
versions again. Each step's sources then carry what their versions recorded,
|
|
@@ -1293,7 +1521,8 @@ warning instead. `ok?` does not prove the history is complete.
|
|
|
1293
1521
|
|
|
1294
1522
|
- **Single-table inheritance.** Results are keyed by the base class, as
|
|
1295
1523
|
PaperTrail stores it: a `Book < Publication` is `["Publication", "12"]`. Use
|
|
1296
|
-
`PaperTrailDiff::Endpoint.identity(record)` to build keys
|
|
1524
|
+
`PaperTrailDiff::Endpoint.identity(record)` to build keys, or
|
|
1525
|
+
`analysis_for(record)` on the result of `analyze_scope` or `report`.
|
|
1297
1526
|
- **Non-integer primary keys**, such as UUIDs, are supported, and so is a string
|
|
1298
1527
|
`versions.item_id` column.
|
|
1299
1528
|
- **Custom version classes** (`has_paper_trail versions: { class_name: }`) are
|
|
@@ -1321,10 +1550,30 @@ the gem raises `AmbiguousVersionOrderError` naming both instead of guessing.
|
|
|
1321
1550
|
Timestamps stored to the second, as on a MySQL `datetime` column, make ties
|
|
1322
1551
|
common. `diagnose` reports this as an error.
|
|
1323
1552
|
|
|
1553
|
+
A record's versions should also be dated in the order they were saved.
|
|
1554
|
+
PaperTrail dates an update with the record's `updated_at` unless the model
|
|
1555
|
+
sets `has_paper_trail synchronize_version_creation_timestamp: false`, so a save
|
|
1556
|
+
that sets `updated_at` itself, such as an import that keeps another system's
|
|
1557
|
+
times, a `touch(time:)`, or one made with timestamps off, can date its version
|
|
1558
|
+
before the one saved before it. Versions are read in time order, so such an update is read
|
|
1559
|
+
before the change it followed, and one dated before the record's `create`
|
|
1560
|
+
reads as the record deleted and created again. When IDs that count up show a
|
|
1561
|
+
record's versions dated out of the order they were saved in, `diagnose` warns
|
|
1562
|
+
with `inverted_version_order`. Set the option on models whose `updated_at`
|
|
1563
|
+
your application sets, and correct the stored `created_at` of versions
|
|
1564
|
+
already saved.
|
|
1565
|
+
|
|
1324
1566
|
`created_at` comes from your application server's clock. A clock that jumps
|
|
1325
1567
|
backwards, or servers whose clocks disagree, can record a later change with an
|
|
1326
1568
|
earlier time. Keep server clocks synchronized.
|
|
1327
1569
|
|
|
1570
|
+
Versions are ordered by when they were stamped, not by when their transactions
|
|
1571
|
+
committed. A transaction stamps its versions while it is open, so one that
|
|
1572
|
+
commits last can still sort first. The gem cannot see commit order. A report
|
|
1573
|
+
can therefore show a state the database never held, and a result for an earlier
|
|
1574
|
+
version or a closed window can change once that transaction commits.
|
|
1575
|
+
[Time windows](#time-windows) explains how to settle a report.
|
|
1576
|
+
|
|
1328
1577
|
Association changes between versions with the same timestamp are placed using
|
|
1329
1578
|
the same order. A few association shapes fall back to PT-AT's own reifier, which
|
|
1330
1579
|
uses timestamps only: a path history reads only approximately, which takes
|
|
@@ -1350,6 +1599,45 @@ precision was never recorded and cannot be reported. A `json` or `jsonb`
|
|
|
1350
1599
|
column also returns times and dates as strings, which PaperTrail leaves as
|
|
1351
1600
|
they are; the gem casts them back to the attribute's type.
|
|
1352
1601
|
|
|
1602
|
+
Two kinds of value come back as something their type cannot cast back:
|
|
1603
|
+
|
|
1604
|
+
- A `json` or `jsonb` `object` column stores a `serialize`d attribute as
|
|
1605
|
+
JSON writes it, so keys come back as strings, and dates, times, and symbols
|
|
1606
|
+
inside it as strings. The gem reads that attribute in this form on every
|
|
1607
|
+
side, the current record's too, so a value nothing changed is not reported
|
|
1608
|
+
as changed: `{ due: Date.new(2026, 11, 3) }` appears as
|
|
1609
|
+
`{ "due" => "2026-11-03" }`.
|
|
1610
|
+
- PaperTrail's JSON serializer stores a `binary` column as
|
|
1611
|
+
`{ "value" => bytes }`, and cannot store bytes that are not UTF-8. The gem
|
|
1612
|
+
reads the bytes. On PostgreSQL, PaperTrail cannot read such a `bytea` value
|
|
1613
|
+
back at all: its `reify` raises `TypeError`, and so does the gem.
|
|
1614
|
+
|
|
1615
|
+
### Writing history in tests
|
|
1616
|
+
|
|
1617
|
+
To give versions fixed times in a test, save them at those times with
|
|
1618
|
+
`travel_to`:
|
|
1619
|
+
|
|
1620
|
+
```ruby
|
|
1621
|
+
travel_to(Time.zone.local(2026, 8, 15, 9, 1)) do
|
|
1622
|
+
PaperTrail.request(whodunnit: "alice") { article.update!(title: "Published") }
|
|
1623
|
+
end
|
|
1624
|
+
```
|
|
1625
|
+
|
|
1626
|
+
If you change `created_at` after saving instead, change every version saved
|
|
1627
|
+
in the same transaction, not only the ones you check. PT-AT gives all of
|
|
1628
|
+
them the same `transaction_id`, including versions of other models saved by
|
|
1629
|
+
callbacks. A version left at the time the test ran makes that transaction
|
|
1630
|
+
seem to last from your chosen time until today. A window edge in between
|
|
1631
|
+
then moves back to the transaction's start (see [Time windows](#time-windows)),
|
|
1632
|
+
and the window can lose the changes the test expects.
|
|
1633
|
+
|
|
1634
|
+
```ruby
|
|
1635
|
+
def set_version_time(version, time)
|
|
1636
|
+
same = version.transaction_id && { transaction_id: version.transaction_id }
|
|
1637
|
+
PaperTrail::Version.where(same || { id: version.id }).update_all(created_at: time)
|
|
1638
|
+
end
|
|
1639
|
+
```
|
|
1640
|
+
|
|
1353
1641
|
## Instrumentation
|
|
1354
1642
|
|
|
1355
1643
|
The gem never logs. It emits `ActiveSupport::Notifications` events you can
|
|
@@ -1362,6 +1650,7 @@ subscribe to:
|
|
|
1362
1650
|
- `load_live_endpoints.paper_trail_diff`
|
|
1363
1651
|
- `prepare_history.paper_trail_diff`
|
|
1364
1652
|
- `ambiguous_association_boundary.paper_trail_diff`
|
|
1653
|
+
- `moved_window.paper_trail_diff`, when a [window edge moves](#time-windows)
|
|
1365
1654
|
|
|
1366
1655
|
```ruby
|
|
1367
1656
|
ActiveSupport::Notifications.subscribe(/\.paper_trail_diff\z/) do |name, start, finish, _id, payload|
|
|
@@ -1369,10 +1658,15 @@ ActiveSupport::Notifications.subscribe(/\.paper_trail_diff\z/) do |name, start,
|
|
|
1369
1658
|
end
|
|
1370
1659
|
```
|
|
1371
1660
|
|
|
1372
|
-
Payloads contain counts, model names, association paths, and
|
|
1373
|
-
record data. To see the SQL for one call, subscribe to `sql.active_record`
|
|
1661
|
+
Payloads contain counts, model names, ids, times, association paths, and
|
|
1662
|
+
options, never record data. To see the SQL for one call, subscribe to `sql.active_record`
|
|
1374
1663
|
around it with `ActiveSupport::Notifications.subscribed`.
|
|
1375
1664
|
|
|
1665
|
+
`PaperTrailDiff.deprecator` warns when an option is deprecated; none is now. In
|
|
1666
|
+
a Rails app, register it with
|
|
1667
|
+
`Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`
|
|
1668
|
+
to handle its warnings as the app's own.
|
|
1669
|
+
|
|
1376
1670
|
## Errors
|
|
1377
1671
|
|
|
1378
1672
|
All errors inherit from `PaperTrailDiff::Error`.
|
|
@@ -1380,13 +1674,11 @@ All errors inherit from `PaperTrailDiff::Error`.
|
|
|
1380
1674
|
| Error | Raised when |
|
|
1381
1675
|
| --- | --- |
|
|
1382
1676
|
| `ConfigurationError` | An option is invalid |
|
|
1383
|
-
| `UnsupportedBatchPathError` | No longer raised; kept until `allow_expensive:` is removed |
|
|
1384
1677
|
| `InvalidEndpointError` | A record is unsaved, destroyed, or has unsaved changes, or `recorded_changes` is given something other than a version |
|
|
1385
|
-
| `UnloadedAssociationError` | The deprecated `reload_live_endpoints: false`, and an association is not loaded |
|
|
1386
1678
|
| `VersionMismatchError` | Two endpoints belong to different records |
|
|
1387
1679
|
| `ReversedEndpointsError` | Two versions are given newest first |
|
|
1388
1680
|
| `InvalidTimelineRangeError` | A range is invalid, for example `within:` with `from:`, or `:last` |
|
|
1389
|
-
| `InvalidTimeRangeError` | `within:` is not a
|
|
1681
|
+
| `InvalidTimeRangeError` | `within:` is not a range with a beginning, in time order |
|
|
1390
1682
|
| `IncompleteTimeRangeError` | A window's last change has no later version and the record has no saved row to read instead |
|
|
1391
1683
|
| `AmbiguousVersionOrderError` | Versions cannot be ordered (see [version order](#version-order)) |
|
|
1392
1684
|
| `BatchLimitExceededError` | More records are selected than `limit:` allows |
|
|
@@ -1409,8 +1701,47 @@ Results can only be as complete as the history PaperTrail and PT-AT recorded.
|
|
|
1409
1701
|
[how PaperTrail stores history](#how-papertrail-stores-history).
|
|
1410
1702
|
- Deleted versions, schema changes, and serializer changes can affect how old
|
|
1411
1703
|
versions read.
|
|
1412
|
-
-
|
|
1413
|
-
|
|
1704
|
+
- With PaperTrail's default YAML serializer, PaperTrail 16 and 17 decode a
|
|
1705
|
+
`time` (time of day) column as `nil`, in `reify` and `changeset` alike,
|
|
1706
|
+
unless the column is time-zone aware, as a Rails app's are, and the time
|
|
1707
|
+
zone is UTC. The gem reads the time each version recorded, including in
|
|
1708
|
+
the records it passes to a callable `historical_filter:`, but your own
|
|
1709
|
+
calls to those PaperTrail methods still return `nil`. PaperTrail's JSON
|
|
1710
|
+
serializer, and SQL Server, whose adapter stores a time its own way, are
|
|
1711
|
+
not affected. Snapshots and diffs show every time of day on 2000-01-01 in
|
|
1712
|
+
its own zone, as Active Record 8.1 reads one. Active Record before 8.1
|
|
1713
|
+
reads a zone-aware time from the database on 2000-01-01 in UTC, so
|
|
1714
|
+
`record.opens_at` can show another date than the snapshot of that time.
|
|
1715
|
+
- Each call reads its history and live rows in one snapshot on PostgreSQL and
|
|
1716
|
+
MySQL (through mysql2 or trilogy), and on adapters built on them such as
|
|
1717
|
+
PostGIS, so a commit that lands during the call is seen by none of its
|
|
1718
|
+
statements. On SQL Server it does so only when the database allows snapshot
|
|
1719
|
+
isolation, which you turn on with
|
|
1720
|
+
`ALTER DATABASE your_database SET ALLOW_SNAPSHOT_ISOLATION ON`; each call
|
|
1721
|
+
checks the setting first. The snapshot covers the database of the record's
|
|
1722
|
+
model and its versions; an associated model on another database is read
|
|
1723
|
+
outside it. A call made inside a transaction of your own keeps that
|
|
1724
|
+
transaction's isolation level. To make the whole call see one snapshot,
|
|
1725
|
+
start that transaction at `REPEATABLE READ` or stricter, or at `SNAPSHOT` on
|
|
1726
|
+
SQL Server. SQLite, and SQL Server without snapshot isolation, take no
|
|
1727
|
+
snapshot, so a commit during a call can appear in some of its statements
|
|
1728
|
+
and not others. A long call holds its snapshot until it ends: on PostgreSQL
|
|
1729
|
+
that can keep VACUUM from reclaiming old row versions, on MySQL it keeps
|
|
1730
|
+
undo history, and on SQL Server it keeps row versions in `tempdb`.
|
|
1731
|
+
- A savepoint that rolls back, or another transaction saving in the same tree
|
|
1732
|
+
at the same time, can split one transaction into several transaction groups;
|
|
1733
|
+
see [one step per transaction group](#one-step-per-transaction-group-transaction).
|
|
1734
|
+
- Two transactions that save in one record's tree at the same time, so that
|
|
1735
|
+
their versions interleave, are read in the order of their versions. A
|
|
1736
|
+
version reads the records its own transaction saved as they stood before
|
|
1737
|
+
the transaction, but a version of the other transaction reads them as they
|
|
1738
|
+
stood after the change saved before it. So a record that one transaction
|
|
1739
|
+
changed and changed back, such as a comment it created and deleted again,
|
|
1740
|
+
can appear in the other's steps, crediting that transaction with adding
|
|
1741
|
+
or removing it, and a window's starting state and diff can hold it too.
|
|
1742
|
+
Row locks keep the two from saving the same record, so this needs both to
|
|
1743
|
+
save different records of one tree within moments of each other. See
|
|
1744
|
+
[version order](#version-order).
|
|
1414
1745
|
- HABTM membership history exists only where PT-AT recorded it in a
|
|
1415
1746
|
transaction, and only for the root record without a scope: a scoped HABTM,
|
|
1416
1747
|
or one below the root, raises `UnsupportedAssociationError`, and a transaction that another record with
|