paper_trail_diff 0.16.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 +566 -1
- data/README.md +42 -7
- data/docs/architecture.md +7 -5
- data/docs/performance.md +86 -38
- data/docs/reference.md +309 -92
- data/docs/testing.md +240 -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 +3 -13
- 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 +29 -29
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -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 +74 -40
- 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 +194 -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 +19 -5
- 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 +16 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
- 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 -37
- data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
- data/lib/paper_trail_diff/deprecation.rb +4 -43
- data/lib/paper_trail_diff/diagnostics.rb +1 -2
- 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 +40 -45
- data/lib/paper_trail_diff/prepared_activity_index.rb +170 -42
- 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 +20 -31
- data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
- data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
- 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 +41 -19
- 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 +7 -17
- data/lib/paper_trail_diff/scope_ranking.rb +16 -22
- data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
- data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
- 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 +37 -20
- data/lib/paper_trail_diff/time_version_range.rb +5 -10
- data/lib/paper_trail_diff/timeline_builder.rb +3 -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 +192 -91
- 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 +37 -21
- 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 +32 -0
- data/lib/paper_trail_diff/version_table.rb +12 -8
- data/lib/paper_trail_diff.rb +28 -42
- 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 +0 -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 +11 -4
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -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 +36 -2
- 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 +121 -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 +15 -6
- 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 +9 -8
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
- 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 -12
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
- 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 +9 -6
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +103 -14
- 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 +9 -12
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
- 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 +27 -8
- 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 +0 -2
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
- 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 -8
- data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -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 +111 -52
- 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 +15 -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 +13 -0
- data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
- data/sig/generated/paper_trail_diff.rbs +16 -16
- metadata +28 -6
- 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
|
@@ -84,6 +84,8 @@ Six things follow from this:
|
|
|
84
84
|
leave it out.
|
|
85
85
|
[`recorded_changes`](#what-a-version-recorded) reads what a version itself
|
|
86
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.
|
|
87
89
|
- **A record created without a version looks as if it always existed.** A
|
|
88
90
|
row written with versioning off, or imported with `insert_all`, has no
|
|
89
91
|
`create` version, so history never reports it as added: its earliest
|
|
@@ -172,20 +174,38 @@ all of today and `august...september` stops before September 1. A string is a
|
|
|
172
174
|
time in `Time.zone` unless it names an offset. Without `Time.zone`, both are
|
|
173
175
|
read in UTC, never in the server's own zone.
|
|
174
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
|
+
|
|
175
181
|
A window edge that falls inside a transaction moves back to where that
|
|
176
182
|
transaction began, so the whole transaction is in the later window, as it is
|
|
177
|
-
when a range [starts or ends at a version](#choosing-a-range).
|
|
178
|
-
|
|
179
|
-
and the `touch: true` article version saved with it
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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.
|
|
183
202
|
|
|
184
203
|
`analysis.window` is the window an `Analysis` covers after any such move, as a
|
|
185
|
-
Ruby range
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
moved window begins before the time
|
|
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.
|
|
189
209
|
|
|
190
210
|
```ruby
|
|
191
211
|
analysis = PaperTrailDiff.analyze_many(articles, within: window, activity: true).values.first
|
|
@@ -231,19 +251,14 @@ in the step for that record's last recorded change.
|
|
|
231
251
|
If the window's last change destroyed the record, the window closes on that
|
|
232
252
|
deletion instead. See [a destroyed record](#a-destroyed-record).
|
|
233
253
|
|
|
234
|
-
`close_on: :current` is deprecated and has no effect; passing it warns through
|
|
235
|
-
`PaperTrailDiff.deprecator`. Remove it. In a Rails app, register the deprecator
|
|
236
|
-
with `Rails.application.deprecators[:paper_trail_diff] = PaperTrailDiff.deprecator`
|
|
237
|
-
to handle its warnings as the app's own.
|
|
238
|
-
|
|
239
254
|
`timeline` returns no steps for a window with no versions of the root record.
|
|
240
255
|
`activity_timeline` still reports chosen associations that changed in such a
|
|
241
256
|
window.
|
|
242
257
|
|
|
243
258
|
### Reporting only some changes: `version_scope:`
|
|
244
259
|
|
|
245
|
-
`version_scope:` narrows which
|
|
246
|
-
|
|
260
|
+
`version_scope:` narrows which changes are reported. It receives the version
|
|
261
|
+
relation and returns a narrower one:
|
|
247
262
|
|
|
248
263
|
```ruby
|
|
249
264
|
user_edits = ->(scope) { scope.where.not(whodunnit: nil) }
|
|
@@ -263,17 +278,29 @@ It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
|
|
|
263
278
|
reported alice: what alice changed bob: what bob changed
|
|
264
279
|
```
|
|
265
280
|
|
|
266
|
-
-
|
|
267
|
-
has
|
|
268
|
-
|
|
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.
|
|
269
294
|
- In `analyze_scope` and `report`, it also chooses which records are selected:
|
|
270
|
-
a record
|
|
271
|
-
the window
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
-
|
|
275
|
-
|
|
276
|
-
|
|
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`.
|
|
277
304
|
|
|
278
305
|
## compare
|
|
279
306
|
|
|
@@ -314,8 +341,7 @@ diff.to_h
|
|
|
314
341
|
- A current record must be saved, not destroyed, and have no unsaved changes.
|
|
315
342
|
The gem reloads it, so in-memory edits and cached associations are ignored.
|
|
316
343
|
- Options: `associations:`, `ignore:`, and `allow_approximate:` (see
|
|
317
|
-
[costly associations](#costly-associations)).
|
|
318
|
-
deprecated (see [reusing loaded records](#reusing-loaded-records)).
|
|
344
|
+
[costly associations](#costly-associations)).
|
|
319
345
|
|
|
320
346
|
## compare_many
|
|
321
347
|
|
|
@@ -345,21 +371,6 @@ diffs.fetch(["Order", orders.first.id.to_s]) # => PaperTrailDiff::Diff
|
|
|
345
371
|
If you look up versions yourself, do it in bulk. Looking up one record at a
|
|
346
372
|
time brings back the per-record queries this method avoids.
|
|
347
373
|
|
|
348
|
-
### Reusing loaded records
|
|
349
|
-
|
|
350
|
-
Every method reloads the current records it compares with, together with the
|
|
351
|
-
requested associations, in a query for the records and one per association
|
|
352
|
-
level. `reload_live_endpoints: false` on `compare`, `compare_many`, and
|
|
353
|
-
`activity_timeline` skips that reload and reads your loaded objects instead.
|
|
354
|
-
It is deprecated and will be removed: it saves those few queries per call (2
|
|
355
|
-
for 500 articles with their comments), and the values then come from objects
|
|
356
|
-
that may be stale. Until it is removed it still works,
|
|
357
|
-
with a warning. A requested association that is not loaded raises
|
|
358
|
-
`UnloadedAssociationError`, and one with a `limit` or `offset`, directly or in
|
|
359
|
-
a part it goes through, or a scope that takes the owner, is read again for
|
|
360
|
-
each record, because Active Record's `preload` applies a limit to all the
|
|
361
|
-
records it loads together.
|
|
362
|
-
|
|
363
374
|
## timeline
|
|
364
375
|
|
|
365
376
|
`timeline(record)` returns one step for each pair of neighboring versions of the
|
|
@@ -429,12 +440,26 @@ end
|
|
|
429
440
|
current record. You do not need to save the article after each comment change.
|
|
430
441
|
- Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`,
|
|
431
442
|
`version_scope:`, `snapshots:`, `group:`, `recorded_changes:`,
|
|
432
|
-
`allow_approximate:`.
|
|
433
|
-
[reusing loaded records](#reusing-loaded-records)).
|
|
443
|
+
`allow_approximate:`.
|
|
434
444
|
|
|
435
445
|
### One person's changes
|
|
436
446
|
|
|
437
|
-
|
|
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:
|
|
438
463
|
|
|
439
464
|
<!-- executable:readme-person-changes -->
|
|
440
465
|
```ruby
|
|
@@ -452,13 +477,9 @@ authors = attributed.group_by { |step| step.source_boundary.whodunnit }
|
|
|
452
477
|
.transform_values(&:length)
|
|
453
478
|
```
|
|
454
479
|
|
|
455
|
-
This includes changes to associations, which `version_scope:` cannot see.
|
|
456
|
-
Filter after the call rather than asking the gem for fewer versions: every step
|
|
457
|
-
has to be rebuilt anyway for each one to be correct, so filtering earlier saves
|
|
458
|
-
nothing.
|
|
459
|
-
|
|
460
480
|
For many records, use `report` or `analyze_many(..., activity: true)` instead of
|
|
461
|
-
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.
|
|
462
483
|
|
|
463
484
|
### One step per transaction: `group: :transaction`
|
|
464
485
|
|
|
@@ -474,13 +495,22 @@ PaperTrailDiff.activity_timeline(article, associations: [:comments], group: :tra
|
|
|
474
495
|
it. A field set and then restored inside the transaction is not reported.
|
|
475
496
|
- Its `source_boundary` is the first event in the transaction. That event's
|
|
476
497
|
author is not necessarily the author of every grouped change. `step.sources`
|
|
477
|
-
lists every event in the transaction, each with its own author, except
|
|
478
|
-
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.
|
|
479
504
|
- Versions without a `transaction_id` are never grouped.
|
|
480
505
|
- A savepoint that rolls back can split one transaction into more than one
|
|
481
506
|
group. PT-AT clears the transaction id when the savepoint rolls back, so the
|
|
482
507
|
versions the transaction saves afterwards form a separate group. Releasing
|
|
483
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.
|
|
484
514
|
- Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
|
|
485
515
|
`activity: true`, and by `report`.
|
|
486
516
|
|
|
@@ -509,6 +539,7 @@ step.from_snapshot.associations["comments"].records.first.attributes["author"]
|
|
|
509
539
|
record did not exist yet.
|
|
510
540
|
- Also accepted by `analyze`, `analyze_many`, and `analyze_scope` with
|
|
511
541
|
`activity: true`, and by `report`.
|
|
542
|
+
- [`net_changes`](#net-changes) reads them, so it needs this option.
|
|
512
543
|
|
|
513
544
|
### What each event recorded: `recorded_changes: true`
|
|
514
545
|
|
|
@@ -538,10 +569,11 @@ end
|
|
|
538
569
|
- Each boundary's `recorded_changes` is what
|
|
539
570
|
`PaperTrailDiff.recorded_changes(version)` returns for its version: `nil`
|
|
540
571
|
when nothing was recorded, and always `nil` for the current record. The
|
|
541
|
-
versions are already loaded, so this adds no queries
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
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.
|
|
545
577
|
- Without the option, `recorded_changes` raises `ConfigurationError` instead of
|
|
546
578
|
returning `nil`, so a missing option cannot look like a version that recorded
|
|
547
579
|
nothing.
|
|
@@ -628,9 +660,10 @@ analysis.to_h(snapshots: true, metadata: true)
|
|
|
628
660
|
- `from_snapshot` is the record as it was when the range began: before the
|
|
629
661
|
first change in a window, or before the change of the version you passed as
|
|
630
662
|
`from:`. With `version_scope:`, a window begins at the first change the
|
|
631
|
-
filter keeps
|
|
632
|
-
|
|
633
|
-
`to_snapshot`, which
|
|
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.
|
|
634
667
|
- To read the record at one version, with its values typed and its
|
|
635
668
|
associations, take `from_snapshot` from a range that starts there:
|
|
636
669
|
`PaperTrailDiff.analyze(article, from: version, to: article).from_snapshot`.
|
|
@@ -695,7 +728,11 @@ report.roots # the selected records, in relation order
|
|
|
695
728
|
report.unreachable # identities of selected records that no longer exist
|
|
696
729
|
report.deleted # { identity => Analysis or nil }, with include_deleted: true
|
|
697
730
|
|
|
698
|
-
|
|
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
|
|
699
736
|
```
|
|
700
737
|
|
|
701
738
|
It takes the same options as `analyze_many`, plus `limit:`, `historical_filter:`,
|
|
@@ -704,9 +741,8 @@ all history.
|
|
|
704
741
|
|
|
705
742
|
### report
|
|
706
743
|
|
|
707
|
-
`report(scope, since:, limit:)` is `analyze_scope` with
|
|
708
|
-
|
|
709
|
-
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":
|
|
710
746
|
|
|
711
747
|
```ruby
|
|
712
748
|
report = PaperTrailDiff.report(Article.all, since: 1.day.ago, limit: 100)
|
|
@@ -727,7 +763,7 @@ and `allow_approximate:`.
|
|
|
727
763
|
versions and cannot show a change to its associations alone, so only a
|
|
728
764
|
record's own version selects it. With
|
|
729
765
|
[`version_scope:`](#reporting-only-some-changes-version_scope), only the
|
|
730
|
-
|
|
766
|
+
versions the filter keeps select it, the record's own and its associations'.
|
|
731
767
|
- **An analysis can still be empty.** A record is selected by any version on its
|
|
732
768
|
paths, but its analysis compares only the state you requested. A join row
|
|
733
769
|
whose role changed, or a version that touched only ignored columns, selects a
|
|
@@ -739,9 +775,17 @@ and `allow_approximate:`.
|
|
|
739
775
|
selected, the call raises `BatchLimitExceededError` instead of returning part
|
|
740
776
|
of the answer. Narrow the relation or the window, or raise the limit.
|
|
741
777
|
- **To paginate, use the relation.** Its `order`, `limit`, and `offset` choose
|
|
742
|
-
the page. Without an `order`, records are taken in ascending ID order.
|
|
743
|
-
|
|
744
|
-
|
|
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)`.
|
|
745
789
|
- Selection still scans the versions in the window, so keep windows reasonable
|
|
746
790
|
for large tables. Each requested association adds one query per level, however
|
|
747
791
|
many records it selects. Changes to associations are found from PT-AT's
|
|
@@ -797,8 +841,11 @@ report = PaperTrailDiff.report(
|
|
|
797
841
|
)
|
|
798
842
|
```
|
|
799
843
|
|
|
800
|
-
The filter checks the record as it was when
|
|
801
|
-
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
|
|
802
849
|
hash, every key must be equal (`==`) once both sides are cast to the
|
|
803
850
|
attribute's type, as `where` casts its values: `{ status: :published }` matches
|
|
804
851
|
an enum, and a date or time matches whether the history stored it as YAML or
|
|
@@ -909,7 +956,7 @@ such a path and names it. Remove it from `associations:`, rewrite its scope as
|
|
|
909
956
|
plain conditions on the target's own columns, or pass `allow_approximate:
|
|
910
957
|
true` to accept PT-AT's answer, which also accepts its cost of queries per
|
|
911
958
|
record in batch methods. A comparison of two current records reads no history
|
|
912
|
-
and needs no opt-in.
|
|
959
|
+
and needs no opt-in.
|
|
913
960
|
|
|
914
961
|
A polymorphic `belongs_to` is loaded together too, with one query per target
|
|
915
962
|
class. Its classes are known only from the records, though, so batch methods
|
|
@@ -1153,6 +1200,7 @@ for numeric IDs).
|
|
|
1153
1200
|
| `ActivityStep` | one `activity_timeline` step |
|
|
1154
1201
|
| `ActivityBoundary` | one end of a step |
|
|
1155
1202
|
| `ChangeRow` | one row from `change_rows` |
|
|
1203
|
+
| `NetChange` | one record's entry from `net_changes` |
|
|
1156
1204
|
| `Analysis` | result of `analyze` |
|
|
1157
1205
|
| `ScopedAnalysis` | result of `analyze_scope` and `report` |
|
|
1158
1206
|
| `TraversalEntry`, `RecordReference` | entries from `each_change` and `each_entry` |
|
|
@@ -1205,7 +1253,7 @@ record reachable through two requested paths appears at both.
|
|
|
1205
1253
|
### Change rows
|
|
1206
1254
|
|
|
1207
1255
|
For a table or an export, `change_rows` flattens activity into one row per
|
|
1208
|
-
change, each
|
|
1256
|
+
change, each credited to the version that made it:
|
|
1209
1257
|
|
|
1210
1258
|
```ruby
|
|
1211
1259
|
steps.last.change_rows # one activity step
|
|
@@ -1219,14 +1267,15 @@ row.from # nil for :added
|
|
|
1219
1267
|
row.to # nil for :removed
|
|
1220
1268
|
row.record # a RecordReference, or nil for the root
|
|
1221
1269
|
row.association_path # ["comments"], or [] for the root
|
|
1222
|
-
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
|
|
1223
1272
|
row.to_h # the above, plus version_id, event, whodunnit, recorded_at,
|
|
1224
1273
|
# and transaction_id
|
|
1225
1274
|
```
|
|
1226
1275
|
|
|
1227
1276
|
- An edited field is one `:changed` row. A record that appeared or disappeared
|
|
1228
1277
|
gets an `:added` or `:removed` row with `attribute` `nil`, then a row for each
|
|
1229
|
-
field that
|
|
1278
|
+
field that is not `nil` and for each record it holds.
|
|
1230
1279
|
- A replaced `belongs_to` or `has_one` target gives the old record `:removed`
|
|
1231
1280
|
rows, then the new one `:added` rows.
|
|
1232
1281
|
- Rows follow the diff's walking order, and an analysis's rows follow its steps
|
|
@@ -1234,6 +1283,112 @@ row.to_h # the above, plus version_id, event, whodunnit, recorded_at
|
|
|
1234
1283
|
- `Analysis#change_rows` raises `ConfigurationError` without `activity: true`.
|
|
1235
1284
|
`report.change_rows` leaves out a deleted record without destroy history.
|
|
1236
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
|
+
|
|
1237
1392
|
## JSON columns
|
|
1238
1393
|
|
|
1239
1394
|
A `json` or `jsonb` column is compared as one value. `nested_changes` reports
|
|
@@ -1248,6 +1403,8 @@ PaperTrailDiff.nested_changes(from_value, to_value) # also accepts two values
|
|
|
1248
1403
|
```
|
|
1249
1404
|
|
|
1250
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.
|
|
1251
1408
|
- Arrays are compared by their elements, not positions. An `ArrayChange` has
|
|
1252
1409
|
`added`, `removed`, and `reordered?`, plus the whole `from` and `to`. Objects
|
|
1253
1410
|
inside arrays are compared whole.
|
|
@@ -1295,6 +1452,10 @@ Other details:
|
|
|
1295
1452
|
- Unlike PaperTrail's `version.changeset`, it never loads the record. That
|
|
1296
1453
|
saves a query per version, and a deleted record's values keep their types,
|
|
1297
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.
|
|
1298
1459
|
|
|
1299
1460
|
For activity steps, pass `recorded_changes: true` instead of loading the
|
|
1300
1461
|
versions again. Each step's sources then carry what their versions recorded,
|
|
@@ -1360,7 +1521,8 @@ warning instead. `ok?` does not prove the history is complete.
|
|
|
1360
1521
|
|
|
1361
1522
|
- **Single-table inheritance.** Results are keyed by the base class, as
|
|
1362
1523
|
PaperTrail stores it: a `Book < Publication` is `["Publication", "12"]`. Use
|
|
1363
|
-
`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`.
|
|
1364
1526
|
- **Non-integer primary keys**, such as UUIDs, are supported, and so is a string
|
|
1365
1527
|
`versions.item_id` column.
|
|
1366
1528
|
- **Custom version classes** (`has_paper_trail versions: { class_name: }`) are
|
|
@@ -1388,6 +1550,19 @@ the gem raises `AmbiguousVersionOrderError` naming both instead of guessing.
|
|
|
1388
1550
|
Timestamps stored to the second, as on a MySQL `datetime` column, make ties
|
|
1389
1551
|
common. `diagnose` reports this as an error.
|
|
1390
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
|
+
|
|
1391
1566
|
`created_at` comes from your application server's clock. A clock that jumps
|
|
1392
1567
|
backwards, or servers whose clocks disagree, can record a later change with an
|
|
1393
1568
|
earlier time. Keep server clocks synchronized.
|
|
@@ -1424,6 +1599,19 @@ precision was never recorded and cannot be reported. A `json` or `jsonb`
|
|
|
1424
1599
|
column also returns times and dates as strings, which PaperTrail leaves as
|
|
1425
1600
|
they are; the gem casts them back to the attribute's type.
|
|
1426
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
|
+
|
|
1427
1615
|
### Writing history in tests
|
|
1428
1616
|
|
|
1429
1617
|
To give versions fixed times in a test, save them at those times with
|
|
@@ -1474,6 +1662,11 @@ Payloads contain counts, model names, ids, times, association paths, and
|
|
|
1474
1662
|
options, never record data. To see the SQL for one call, subscribe to `sql.active_record`
|
|
1475
1663
|
around it with `ActiveSupport::Notifications.subscribed`.
|
|
1476
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
|
+
|
|
1477
1670
|
## Errors
|
|
1478
1671
|
|
|
1479
1672
|
All errors inherit from `PaperTrailDiff::Error`.
|
|
@@ -1481,13 +1674,11 @@ All errors inherit from `PaperTrailDiff::Error`.
|
|
|
1481
1674
|
| Error | Raised when |
|
|
1482
1675
|
| --- | --- |
|
|
1483
1676
|
| `ConfigurationError` | An option is invalid |
|
|
1484
|
-
| `UnsupportedBatchPathError` | No longer raised; kept until `allow_expensive:` is removed |
|
|
1485
1677
|
| `InvalidEndpointError` | A record is unsaved, destroyed, or has unsaved changes, or `recorded_changes` is given something other than a version |
|
|
1486
|
-
| `UnloadedAssociationError` | The deprecated `reload_live_endpoints: false`, and an association is not loaded |
|
|
1487
1678
|
| `VersionMismatchError` | Two endpoints belong to different records |
|
|
1488
1679
|
| `ReversedEndpointsError` | Two versions are given newest first |
|
|
1489
1680
|
| `InvalidTimelineRangeError` | A range is invalid, for example `within:` with `from:`, or `:last` |
|
|
1490
|
-
| `InvalidTimeRangeError` | `within:` is not a
|
|
1681
|
+
| `InvalidTimeRangeError` | `within:` is not a range with a beginning, in time order |
|
|
1491
1682
|
| `IncompleteTimeRangeError` | A window's last change has no later version and the record has no saved row to read instead |
|
|
1492
1683
|
| `AmbiguousVersionOrderError` | Versions cannot be ordered (see [version order](#version-order)) |
|
|
1493
1684
|
| `BatchLimitExceededError` | More records are selected than `limit:` allows |
|
|
@@ -1510,21 +1701,47 @@ Results can only be as complete as the history PaperTrail and PT-AT recorded.
|
|
|
1510
1701
|
[how PaperTrail stores history](#how-papertrail-stores-history).
|
|
1511
1702
|
- Deleted versions, schema changes, and serializer changes can affect how old
|
|
1512
1703
|
versions read.
|
|
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.
|
|
1513
1715
|
- Each call reads its history and live rows in one snapshot on PostgreSQL and
|
|
1514
1716
|
MySQL (through mysql2 or trilogy), and on adapters built on them such as
|
|
1515
1717
|
PostGIS, so a commit that lands during the call is seen by none of its
|
|
1516
|
-
statements.
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
1520
|
-
|
|
1521
|
-
|
|
1522
|
-
|
|
1523
|
-
|
|
1524
|
-
|
|
1525
|
-
|
|
1526
|
-
|
|
1527
|
-
|
|
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).
|
|
1528
1745
|
- HABTM membership history exists only where PT-AT recorded it in a
|
|
1529
1746
|
transaction, and only for the root record without a scope: a scoped HABTM,
|
|
1530
1747
|
or one below the root, raises `UnsupportedAssociationError`, and a transaction that another record with
|