paper_trail_diff 0.17.1 → 0.18.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 +648 -0
- data/QUICKSTART.md +12 -14
- data/README.md +32 -30
- data/docs/architecture.md +65 -29
- data/docs/performance.md +161 -46
- data/docs/reference.md +495 -394
- data/docs/testing.md +9 -15
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
- data/lib/paper_trail_diff/activity_boundary.rb +15 -6
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
- data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
- data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
- data/lib/paper_trail_diff/activity_event.rb +53 -34
- data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
- data/lib/paper_trail_diff/activity_history.rb +28 -34
- data/lib/paper_trail_diff/activity_relationship.rb +3 -26
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
- data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
- data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
- data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
- data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
- data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
- data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
- data/lib/paper_trail_diff/activity_view.rb +2 -0
- data/lib/paper_trail_diff/analysis.rb +6 -5
- data/lib/paper_trail_diff/analysis_batch.rb +21 -17
- data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
- data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
- data/lib/paper_trail_diff/association_discovery.rb +4 -4
- data/lib/paper_trail_diff/association_key.rb +10 -18
- data/lib/paper_trail_diff/association_traversal.rb +72 -92
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
- data/lib/paper_trail_diff/batch_preload.rb +2 -3
- data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
- data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
- data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
- data/lib/paper_trail_diff/candidate_table.rb +160 -0
- data/lib/paper_trail_diff/change_attribution.rb +15 -23
- data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
- data/lib/paper_trail_diff/collection_transition.rb +3 -3
- data/lib/paper_trail_diff/comparison_batch.rb +13 -6
- data/lib/paper_trail_diff/database_time.rb +85 -0
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
- data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
- data/lib/paper_trail_diff/diagnostics.rb +26 -86
- data/lib/paper_trail_diff/endpoint.rb +37 -5
- data/lib/paper_trail_diff/engine.rb +1 -1
- data/lib/paper_trail_diff/errors.rb +0 -6
- data/lib/paper_trail_diff/exact_column_type.rb +96 -0
- data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
- data/lib/paper_trail_diff/instrumentation.rb +0 -8
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
- data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
- data/lib/paper_trail_diff/nested_comparator.rb +42 -10
- data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
- data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
- data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
- data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
- data/lib/paper_trail_diff/prepared_history.rb +27 -177
- data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
- data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
- data/lib/paper_trail_diff/recorded_changes.rb +34 -10
- data/lib/paper_trail_diff/recorded_owner.rb +67 -0
- data/lib/paper_trail_diff/root_version_selection.rb +6 -2
- data/lib/paper_trail_diff/scope_condition.rb +120 -80
- data/lib/paper_trail_diff/scope_ranking.rb +14 -32
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
- data/lib/paper_trail_diff/selection_window.rb +31 -0
- data/lib/paper_trail_diff/snapshot.rb +60 -58
- data/lib/paper_trail_diff/snapshot_members.rb +115 -0
- data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
- data/lib/paper_trail_diff/step.rb +1 -5
- data/lib/paper_trail_diff/stored_form.rb +146 -0
- data/lib/paper_trail_diff/stored_json_values.rb +8 -5
- data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
- data/lib/paper_trail_diff/stored_values.rb +35 -3
- data/lib/paper_trail_diff/support.rb +185 -35
- data/lib/paper_trail_diff/time_of_day.rb +13 -2
- data/lib/paper_trail_diff/time_range.rb +85 -11
- data/lib/paper_trail_diff/time_version_range.rb +5 -1
- data/lib/paper_trail_diff/timeline_builder.rb +5 -11
- data/lib/paper_trail_diff/timeline_range.rb +56 -19
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
- data/lib/paper_trail_diff/total_order.rb +19 -5
- data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
- data/lib/paper_trail_diff/transaction_cut.rb +67 -327
- data/lib/paper_trail_diff/transaction_ends.rb +194 -0
- data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
- data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
- data/lib/paper_trail_diff/value_objects.rb +8 -6
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
- data/lib/paper_trail_diff/version_boundary.rb +0 -29
- data/lib/paper_trail_diff/version_query.rb +49 -1
- data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
- data/lib/paper_trail_diff/version_table.rb +8 -1
- data/lib/paper_trail_diff.rb +56 -110
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
- data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
- data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
- data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
- data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
- data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
- data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
- data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
- data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
- data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
- data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
- data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
- data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
- data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
- data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
- data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
- data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
- data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
- data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
- data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
- data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
- data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
- data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
- data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
- data/sig/generated/paper_trail_diff/errors.rbs +0 -8
- data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
- data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
- data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
- data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
- data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
- data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
- data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
- data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
- data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
- data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
- data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
- data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
- data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
- data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
- data/sig/generated/paper_trail_diff/support.rbs +96 -16
- data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
- data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
- data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
- data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
- data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
- data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
- data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
- data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
- data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
- data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
- data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
- data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
- data/sig/generated/paper_trail_diff.rbs +22 -23
- metadata +28 -20
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
- data/lib/paper_trail_diff/fallback_paths.rb +0 -35
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
- data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
- data/lib/paper_trail_diff/historical_filter.rb +0 -210
- data/lib/paper_trail_diff/own_window.rb +0 -35
- data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
- data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
- data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
- data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
- data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
data/docs/reference.md
CHANGED
|
@@ -10,9 +10,8 @@ including ones most applications never need.
|
|
|
10
10
|
- [Choosing a method](#choosing-a-method)
|
|
11
11
|
- [Choosing a range](#choosing-a-range)
|
|
12
12
|
- [compare](#compare) and [compare_many](#compare_many)
|
|
13
|
-
- [timeline](#timeline)
|
|
14
|
-
|
|
15
|
-
- [analyze](#analyze)
|
|
13
|
+
- [analyze](#analyze), with its [timeline](#timeline) and
|
|
14
|
+
[activity_timeline](#activity_timeline)
|
|
16
15
|
- [Reports for many records](#reports-for-many-records):
|
|
17
16
|
`analyze_many`, `analyze_scope`, `report`
|
|
18
17
|
- [Associations](#associations)
|
|
@@ -24,13 +23,14 @@ including ones most applications never need.
|
|
|
24
23
|
- [Models, schemas, and edge cases](#models-schemas-and-edge-cases)
|
|
25
24
|
- [Instrumentation](#instrumentation)
|
|
26
25
|
- [Errors](#errors)
|
|
26
|
+
- [What results rest on](#what-results-rest-on)
|
|
27
27
|
- [Limitations](#limitations)
|
|
28
28
|
|
|
29
29
|
## Words used on this page
|
|
30
30
|
|
|
31
31
|
| Word | Meaning |
|
|
32
32
|
| --- | --- |
|
|
33
|
-
| Root record | The record you ask about, such as the article in `
|
|
33
|
+
| Root record | The record you ask about, such as the article in `analyze(article)` |
|
|
34
34
|
| Child | An associated record you include with `associations:`, such as a comment |
|
|
35
35
|
| Current state | The record's saved values in the database right now |
|
|
36
36
|
| Snapshot | A read-only copy of a record's data at one point, returned by this gem |
|
|
@@ -75,7 +75,9 @@ Six things follow from this:
|
|
|
75
75
|
with `update_columns` or with versioning off creates no version, but it
|
|
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
|
-
for that record's previous recorded change
|
|
78
|
+
for that record's previous recorded change, whose source is that change's
|
|
79
|
+
version. In [change rows](#change-rows) the write has a row of its own,
|
|
80
|
+
credited to no one.
|
|
79
81
|
Ending a range at a version leaves out only the writes after it. A column
|
|
80
82
|
that `has_paper_trail only:` or `ignore:` leaves out of `object_changes` is
|
|
81
83
|
read the same way, so a key saved with a version is that version's change.
|
|
@@ -83,15 +85,20 @@ Six things follow from this:
|
|
|
83
85
|
in the step of the parent's previous change; pass the column in `ignore:` to
|
|
84
86
|
leave it out.
|
|
85
87
|
[`recorded_changes`](#what-a-version-recorded) reads what a version itself
|
|
86
|
-
recorded, and activity steps
|
|
87
|
-
With it, [change rows](#change-rows) give such a write a row of its own,
|
|
88
|
-
credited to no one.
|
|
88
|
+
recorded, and activity steps [include it](#what-each-event-recorded).
|
|
89
89
|
- **A record created without a version looks as if it always existed.** A
|
|
90
90
|
row written with versioning off, or imported with `insert_all`, has no
|
|
91
91
|
`create` version, so history never reports it as added: its earliest
|
|
92
92
|
version's stored values are its state from before history began, and an
|
|
93
93
|
association includes it there. Rows from before PaperTrail was installed
|
|
94
|
-
are the same, which is usually what you want.
|
|
94
|
+
are the same, which is usually what you want. One such row needs care: a
|
|
95
|
+
child whose first version moves it to another owner. That version stores
|
|
96
|
+
the old owner's key, but PaperTrail-AssociationTracking records the new
|
|
97
|
+
one. Activity steps, `report`, and `analyze_scope` read the old owner from
|
|
98
|
+
the version's stored state, so they report the child leaving it; `compare`
|
|
99
|
+
and `analyze` without `activity: true` find a past owner's children by
|
|
100
|
+
PaperTrail-AssociationTracking's records only, so there the owner it left
|
|
101
|
+
never held it. Every later move is found everywhere.
|
|
95
102
|
- **Pruned history is gone.** With `has_paper_trail limit:`, PaperTrail
|
|
96
103
|
deletes a record's oldest versions, and the earliest one left becomes its
|
|
97
104
|
start: states before it cannot be read, and an older version passed in is
|
|
@@ -103,15 +110,14 @@ Six things follow from this:
|
|
|
103
110
|
| --- | --- |
|
|
104
111
|
| Net difference between two versions, or a version and the current record | `compare(from, to)` |
|
|
105
112
|
| The same for a list of `{ from:, to: }` pairs, one per record | `compare_many(pairs)` |
|
|
106
|
-
|
|
|
107
|
-
|
|
|
108
|
-
| Net difference and timeline together | `analyze(record)` |
|
|
109
|
-
| The same, plus the activity timeline | `analyze(record, activity: true)` |
|
|
113
|
+
| Net difference and each change to one record, version by version | `analyze(record)`, then `diff` and `timeline` |
|
|
114
|
+
| The same, plus each change to its chosen associations, with who made it | `analyze(record, associations: ..., activity: true)`, then `activity_timeline` |
|
|
110
115
|
| Analyses for an array of records | `analyze_many(records)` |
|
|
111
116
|
| Analyses for the records a relation selects, over a time window | `analyze_scope(scope, within:, limit:)` |
|
|
112
117
|
| Recent activity through now, for the records a relation selects | `report(scope, since:, limit:)` |
|
|
113
118
|
|
|
114
|
-
`timeline` and `activity_timeline` differ in which versions
|
|
119
|
+
An analysis's `timeline` and `activity_timeline` differ in which versions
|
|
120
|
+
become steps. Given
|
|
115
121
|
an article with two comment edits between two article versions:
|
|
116
122
|
|
|
117
123
|
```text
|
|
@@ -131,14 +137,14 @@ belongs to one recorded event, which is what you need to show who did what.
|
|
|
131
137
|
|
|
132
138
|
## Choosing a range
|
|
133
139
|
|
|
134
|
-
`
|
|
135
|
-
|
|
140
|
+
`analyze` covers the record's whole history through its current state unless
|
|
141
|
+
you say otherwise:
|
|
136
142
|
|
|
137
143
|
```ruby
|
|
138
|
-
PaperTrailDiff.
|
|
139
|
-
PaperTrailDiff.
|
|
140
|
-
PaperTrailDiff.
|
|
141
|
-
PaperTrailDiff.
|
|
144
|
+
PaperTrailDiff.analyze(article) # all of it
|
|
145
|
+
PaperTrailDiff.analyze(article, from: some_version) # from a version to now
|
|
146
|
+
PaperTrailDiff.analyze(article, from: :first, to: later_version)
|
|
147
|
+
PaperTrailDiff.analyze(article, within: 1.week.ago..Time.current)
|
|
142
148
|
```
|
|
143
149
|
|
|
144
150
|
- `from:` defaults to `:first`, the record's earliest version.
|
|
@@ -166,60 +172,76 @@ and `...` excludes it, which is useful for back-to-back windows:
|
|
|
166
172
|
|
|
167
173
|
```ruby
|
|
168
174
|
window = Time.zone.parse("2026-08-01")...Time.zone.parse("2026-09-01")
|
|
169
|
-
steps = PaperTrailDiff.
|
|
175
|
+
steps = PaperTrailDiff.analyze(article, within: window).timeline
|
|
170
176
|
```
|
|
171
177
|
|
|
178
|
+
A bound is read to the microsecond, as adapters write it into SQL, so a
|
|
179
|
+
version saved in the microsecond of a `Time.now` start is inside the window.
|
|
180
|
+
Where the versions table's `created_at` keeps fewer digits, as a MySQL
|
|
181
|
+
`datetime` column without a precision keeps whole seconds, a bound is read to
|
|
182
|
+
those: a window from 12:00:00.7 starts at 12:00:00, with the versions saved in
|
|
183
|
+
that second.
|
|
184
|
+
|
|
172
185
|
A `Date` bound is a whole day in `Time.zone`, so `Date.today..Date.today` is
|
|
173
186
|
all of today and `august...september` stops before September 1. A string is a
|
|
174
|
-
time in `Time.zone` unless it names an offset
|
|
187
|
+
time in `Time.zone` unless it names an offset, and must name a real day:
|
|
188
|
+
`"12"` or `"2026-02-30"` raises `InvalidTimeRangeError`. Without `Time.zone`, both are
|
|
175
189
|
read in UTC, never in the server's own zone.
|
|
176
190
|
|
|
177
191
|
An endless range, such as `1.day.ago..`, runs through the current saved state:
|
|
178
192
|
it holds every version saved since it began, whatever time its server's clock
|
|
179
193
|
gave it, and it ends at the current record. `report` uses one.
|
|
180
194
|
|
|
181
|
-
A
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
version,
|
|
190
|
-
transaction
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
`
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
195
|
+
A transaction takes effect where it saved its last version, so a window
|
|
196
|
+
reports the transactions that end inside it, each of them whole. One that
|
|
197
|
+
began before the window and ends inside it is reported there, with what it
|
|
198
|
+
saved before the window: a comment edit, say, and the `touch: true` article
|
|
199
|
+
version saved with it after the window's start. One that begins inside the
|
|
200
|
+
window and ends after it is left to the window its last version is in. So
|
|
201
|
+
back-to-back windows, or a `report` with `since:` after an earlier report,
|
|
202
|
+
show each change exactly once, credited to the transaction that made it and to
|
|
203
|
+
its own version, and a
|
|
204
|
+
[transaction group](#one-step-per-transaction-group-transaction) lists every
|
|
205
|
+
version its transaction saved, wherever they fall.
|
|
206
|
+
|
|
207
|
+
Where a transaction ends is read from its version table: the last version it
|
|
208
|
+
saved there, of any record, on the requested paths or not. So every window
|
|
209
|
+
places a transaction alike, whichever of its records the window reads. A
|
|
210
|
+
version table whose ids do not count up, such as one keyed by UUID, names the
|
|
211
|
+
last version by when it was saved. Without associations, each version of the
|
|
212
|
+
record is reported where it was saved, since nothing else of its transaction
|
|
213
|
+
is read. `analyze` without `activity:` compares the record's
|
|
214
|
+
own versions, and report each where it was saved too. With associations, the
|
|
215
|
+
records around each of those versions still read as they stood before every
|
|
216
|
+
transaction that had not ended yet, so an associated record's change is
|
|
217
|
+
reported once, in the step where its transaction ends.
|
|
218
|
+
|
|
219
|
+
A history read without a window begins at the record's first version, or at
|
|
220
|
+
`from:`, before that version's transaction took effect, and ends where the
|
|
221
|
+
transaction of its last version, or of `to:`, took effect. What another
|
|
222
|
+
transaction saved before the start, such as an author it renamed before the
|
|
223
|
+
article was created, is part of the state the history begins in if that
|
|
224
|
+
transaction ended first, and is reported in its own step if it ended later.
|
|
225
|
+
So two ranges that meet at a version report each change once, as the range
|
|
226
|
+
over both does, and `compare` reads a version as both ranges do. A destroyed
|
|
227
|
+
record's history ends where its destruction took effect; a change another
|
|
228
|
+
transaction committed later is not the record's.
|
|
229
|
+
|
|
230
|
+
Two transactions that save in one record's tree at the same time interleave
|
|
231
|
+
their versions. Each is reported as if it ran alone, in the order they end: a
|
|
232
|
+
record reads as it stood before every transaction that had not ended yet.
|
|
233
|
+
|
|
234
|
+
The window itself does not move. `analysis.window` is the window you asked
|
|
235
|
+
for, as a Ruby range, endless for `report` and any other endless window, and
|
|
236
|
+
`nil` when `within:` or `since:` was not given. A step of a transaction that
|
|
237
|
+
began before the window can hold a version saved before `analysis.window`
|
|
238
|
+
begins.
|
|
209
239
|
|
|
210
240
|
```ruby
|
|
211
241
|
analysis = PaperTrailDiff.analyze_many(articles, within: window, activity: true).values.first
|
|
212
|
-
analysis.window # => window
|
|
242
|
+
analysis.window # => window
|
|
213
243
|
```
|
|
214
244
|
|
|
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
245
|
A closed window can still change. PaperTrail stamps a version's `created_at`
|
|
224
246
|
when it builds the version, inside its transaction, and the transaction commits
|
|
225
247
|
later. A transaction that stamped a change inside the window and committed
|
|
@@ -232,12 +254,12 @@ open transactions, so it cannot tell when a window has settled.
|
|
|
232
254
|
To show what the window's last change produced, the gem reads the state just
|
|
233
255
|
before the next change after the window:
|
|
234
256
|
|
|
235
|
-
- With `
|
|
257
|
+
- With `activity: true`, that is the next
|
|
236
258
|
version of the record or of any record on a requested association path. If
|
|
237
259
|
none was recorded after the window, it reads the current record instead,
|
|
238
260
|
and the last step's `to_boundary.kind` is `:current`. So a window that ended
|
|
239
261
|
long ago ends at its own end, even when only a comment changed since.
|
|
240
|
-
- `
|
|
262
|
+
- Without `activity:`, `analyze` compares the record's own
|
|
241
263
|
versions. The last step runs to the record's next version, or to the
|
|
242
264
|
current record when it has none, and an association change made in between
|
|
243
265
|
is part of that step, credited to its author. Use `activity: true` to keep
|
|
@@ -251,7 +273,7 @@ in the step for that record's last recorded change.
|
|
|
251
273
|
If the window's last change destroyed the record, the window closes on that
|
|
252
274
|
deletion instead. See [a destroyed record](#a-destroyed-record).
|
|
253
275
|
|
|
254
|
-
`timeline`
|
|
276
|
+
`timeline` holds no steps for a window with no versions of the root record.
|
|
255
277
|
`activity_timeline` still reports chosen associations that changed in such a
|
|
256
278
|
window.
|
|
257
279
|
|
|
@@ -263,11 +285,12 @@ relation and returns a narrower one:
|
|
|
263
285
|
```ruby
|
|
264
286
|
user_edits = ->(scope) { scope.where.not(whodunnit: nil) }
|
|
265
287
|
|
|
266
|
-
PaperTrailDiff.
|
|
288
|
+
PaperTrailDiff.analyze(article, within: window, version_scope: user_edits)
|
|
267
289
|
```
|
|
268
290
|
|
|
269
|
-
It is accepted by `
|
|
270
|
-
|
|
291
|
+
It is accepted by `analyze`, `analyze_many`, `analyze_scope`, and `report`. It may return the relation narrowed, or an
|
|
292
|
+
array of versions taken from it. Anything else, such as a relation on another
|
|
293
|
+
class or an array of IDs, raises `ConfigurationError`.
|
|
271
294
|
|
|
272
295
|
- Each reported change is compared with the version right after it, even if
|
|
273
296
|
that version is filtered out. So each step shows exactly what that one change
|
|
@@ -281,7 +304,7 @@ It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
|
|
|
281
304
|
- `timeline` looks at the root record's versions only, so someone who only
|
|
282
305
|
edited comments has none for it to report. Activity reports their changes:
|
|
283
306
|
see [one person's changes](#one-persons-changes).
|
|
284
|
-
- In activity (`
|
|
307
|
+
- In activity (`activity: true`, and `report`), it
|
|
285
308
|
chooses the changes on the requested associations as well. A transaction is
|
|
286
309
|
reported whole, every step of it, when the filter keeps any version saved
|
|
287
310
|
in it, of whichever record: PT-AT shows a transaction's changes together, at
|
|
@@ -289,13 +312,17 @@ It is accepted by `timeline`, `activity_timeline`, `analyze`, `analyze_many`,
|
|
|
289
312
|
saved outside a transaction is reported when the filter keeps it. Every
|
|
290
313
|
version is still read, so each step shows what its own change did, and an
|
|
291
314
|
analysis starts at the first change the filter keeps and ends after the
|
|
292
|
-
last
|
|
315
|
+
last, a kept version of a record outside the root's tree being no change
|
|
316
|
+
of the root's. Without associations, the steps are the root's versions the filter
|
|
293
317
|
keeps, as `timeline` reports them.
|
|
294
318
|
- In `analyze_scope` and `report`, it also chooses which records are selected:
|
|
295
319
|
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.
|
|
297
|
-
|
|
298
|
-
|
|
320
|
+
the window, or a version of a record on a requested association. With
|
|
321
|
+
associations, as activity reports them, it keeps a version when it keeps
|
|
322
|
+
any version of that version's transaction, so a record is selected
|
|
323
|
+
whenever its activity reports something. A record changed only by versions
|
|
324
|
+
it drops would have nothing to report, so it is left out, and it does not
|
|
325
|
+
count toward `limit:`.
|
|
299
326
|
- The record and its requested associations keep their versions in one table
|
|
300
327
|
(see [custom version classes](#models-schemas-and-edge-cases)), and the
|
|
301
328
|
filter reads it for all of them. A condition on `item_type` or `item_id`
|
|
@@ -340,8 +367,7 @@ diff.to_h
|
|
|
340
367
|
deleted.
|
|
341
368
|
- A current record must be saved, not destroyed, and have no unsaved changes.
|
|
342
369
|
The gem reloads it, so in-memory edits and cached associations are ignored.
|
|
343
|
-
- Options: `associations
|
|
344
|
-
[costly associations](#costly-associations)).
|
|
370
|
+
- Options: `associations:` and `ignore:`.
|
|
345
371
|
|
|
346
372
|
## compare_many
|
|
347
373
|
|
|
@@ -365,20 +391,61 @@ diffs.fetch(["Order", orders.first.id.to_s]) # => PaperTrailDiff::Diff
|
|
|
365
391
|
record, so `{ from: :first, to: :first }` raises.
|
|
366
392
|
- A record with no versions gets an empty `Diff`.
|
|
367
393
|
- Each record can appear in only one pair, because results are keyed by record.
|
|
368
|
-
- Options: `associations
|
|
369
|
-
[costly associations](#costly-associations)).
|
|
394
|
+
- Options: `associations:` and `ignore:`.
|
|
370
395
|
|
|
371
396
|
If you look up versions yourself, do it in bulk. Looking up one record at a
|
|
372
397
|
time brings back the per-record queries this method avoids.
|
|
373
398
|
|
|
399
|
+
## analyze
|
|
400
|
+
|
|
401
|
+
`analyze(record)` returns an `Analysis` with the net `diff` and the `timeline`
|
|
402
|
+
for one range, reading each version once:
|
|
403
|
+
|
|
404
|
+
```ruby
|
|
405
|
+
analysis = PaperTrailDiff.analyze(article, associations: ["comments.replies"], activity: true)
|
|
406
|
+
|
|
407
|
+
analysis.diff # net change over the range
|
|
408
|
+
analysis.timeline # one step per version of the record
|
|
409
|
+
analysis.activity_timeline # nil unless activity: true
|
|
410
|
+
analysis.from_snapshot # the full state at the start (nil before creation)
|
|
411
|
+
analysis.to_snapshot # the full state at the end
|
|
412
|
+
analysis.window # the time window it covers, or nil without within:
|
|
413
|
+
analysis.to_h(snapshots: true, metadata: true)
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
- See [choosing a range](#choosing-a-range) for `from:`, `to:`, and `within:`.
|
|
417
|
+
- `from_snapshot` is the record as it was when the range began: before the
|
|
418
|
+
first change in a window, or before the change of the version you passed as
|
|
419
|
+
`from:`. With `version_scope:`, a window begins at the first change the
|
|
420
|
+
filter keeps, on the record or, with `activity: true`, on its associations.
|
|
421
|
+
It is `nil` when the record was created inside the range; the state right
|
|
422
|
+
after it was created is then the first activity step's `to_snapshot`, which
|
|
423
|
+
`snapshots: true` keeps.
|
|
424
|
+
- To read the record at one version, with its values typed and its
|
|
425
|
+
associations, take `from_snapshot` from a range that starts there:
|
|
426
|
+
`PaperTrailDiff.analyze(article, from: version, to: article).from_snapshot`.
|
|
427
|
+
Don't decode `version.object` yourself; the gem casts what PaperTrail
|
|
428
|
+
stores, which a `json` column or an enum leaves in another form.
|
|
429
|
+
- When nothing in the range is reported, the analysis is empty: an empty
|
|
430
|
+
`diff` and timelines, and `nil` for `from_snapshot` and `to_snapshot`. Here
|
|
431
|
+
`nil` means no state was read, not that the record did not exist; reading
|
|
432
|
+
one would rebuild the record's whole graph, a cost per record in a batch.
|
|
433
|
+
Use `compare` with a version and the record to see a state that did not
|
|
434
|
+
change.
|
|
435
|
+
- `activity: true` also builds the activity timeline. `snapshots:`, `group:`,
|
|
436
|
+
and `recorded_changes:` apply to the activity timeline and require
|
|
437
|
+
`activity: true`.
|
|
438
|
+
- Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`, `activity:`,
|
|
439
|
+
`version_scope:`, `snapshots:`, `group:`, `recorded_changes:`.
|
|
440
|
+
|
|
374
441
|
## timeline
|
|
375
442
|
|
|
376
|
-
`timeline
|
|
377
|
-
root record, ending at its current state by default. See
|
|
443
|
+
An analysis's `timeline` holds one step for each pair of neighboring versions
|
|
444
|
+
of the root record, ending at its current state by default. See
|
|
378
445
|
[choosing a range](#choosing-a-range) for `from:`, `to:`, and `within:`.
|
|
379
446
|
|
|
380
447
|
```ruby
|
|
381
|
-
steps = PaperTrailDiff.
|
|
448
|
+
steps = PaperTrailDiff.analyze(article).timeline
|
|
382
449
|
|
|
383
450
|
steps.first.diff # a PaperTrailDiff::Diff
|
|
384
451
|
steps.first.empty? # true if nothing reported changed
|
|
@@ -400,17 +467,17 @@ steps.reject(&:empty?) # hide steps with no reported changes
|
|
|
400
467
|
step. `from` and `to` are boundary hashes with `kind`, `version_id`,
|
|
401
468
|
`item_type`, `item_id`, and `recorded_at`. `to_h(metadata: true)` adds author,
|
|
402
469
|
event, transaction ID, and record to each boundary.
|
|
403
|
-
- Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`,
|
|
404
|
-
`version_scope:`, `allow_approximate:`.
|
|
405
470
|
|
|
406
471
|
## activity_timeline
|
|
407
472
|
|
|
408
|
-
`
|
|
409
|
-
recorded event of the root record **or** a chosen association. It ends at
|
|
410
|
-
current record by default.
|
|
473
|
+
With `activity: true`, an analysis's `activity_timeline` holds one step for
|
|
474
|
+
each recorded event of the root record **or** a chosen association. It ends at
|
|
475
|
+
the current record by default.
|
|
411
476
|
|
|
412
477
|
```ruby
|
|
413
|
-
steps = PaperTrailDiff.
|
|
478
|
+
steps = PaperTrailDiff.analyze(
|
|
479
|
+
article, associations: ["comments.replies", :author], activity: true
|
|
480
|
+
).activity_timeline
|
|
414
481
|
|
|
415
482
|
steps.reject(&:empty?).each do |step|
|
|
416
483
|
step.source_boundary.whodunnit # who made this change
|
|
@@ -438,9 +505,6 @@ end
|
|
|
438
505
|
`to_h(snapshots: true)` adds the retained snapshots.
|
|
439
506
|
- A child's change becomes visible at the next recorded event, or at the
|
|
440
507
|
current record. You do not need to save the article after each comment change.
|
|
441
|
-
- Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`,
|
|
442
|
-
`version_scope:`, `snapshots:`, `group:`, `recorded_changes:`,
|
|
443
|
-
`allow_approximate:`.
|
|
444
508
|
|
|
445
509
|
### One person's changes
|
|
446
510
|
|
|
@@ -451,9 +515,10 @@ a version in, on the record or on its associations:
|
|
|
451
515
|
<!-- executable:readme-person-scope -->
|
|
452
516
|
```ruby
|
|
453
517
|
priya = ->(versions) { versions.where(whodunnit: "Priya Shah") }
|
|
454
|
-
steps = PaperTrailDiff.
|
|
455
|
-
article, within: window, associations: %i[comments
|
|
456
|
-
|
|
518
|
+
steps = PaperTrailDiff.analyze(
|
|
519
|
+
article, within: window, associations: %i[comments], activity: true,
|
|
520
|
+
version_scope: priya
|
|
521
|
+
).activity_timeline
|
|
457
522
|
|
|
458
523
|
steps.map { |step| step.source_boundary.whodunnit }.uniq # ["Priya Shah"]
|
|
459
524
|
```
|
|
@@ -463,9 +528,9 @@ To count everyone's changes from one read, group the steps in Ruby by
|
|
|
463
528
|
|
|
464
529
|
<!-- executable:readme-person-changes -->
|
|
465
530
|
```ruby
|
|
466
|
-
steps = PaperTrailDiff.
|
|
467
|
-
article, within: window, associations: %i[comments
|
|
468
|
-
)
|
|
531
|
+
steps = PaperTrailDiff.analyze(
|
|
532
|
+
article, within: window, associations: %i[comments], activity: true
|
|
533
|
+
).activity_timeline
|
|
469
534
|
|
|
470
535
|
attributed = steps.reject(&:empty?)
|
|
471
536
|
by_priya = attributed.select { |step| step.source_boundary.whodunnit == "Priya Shah" }
|
|
@@ -478,7 +543,7 @@ authors = attributed.group_by { |step| step.source_boundary.whodunnit }
|
|
|
478
543
|
```
|
|
479
544
|
|
|
480
545
|
For many records, use `report` or `analyze_many(..., activity: true)` instead of
|
|
481
|
-
calling `
|
|
546
|
+
calling `analyze` in a loop, so the database work is shared. With
|
|
482
547
|
`version_scope:`, `report` selects only the records that person changed.
|
|
483
548
|
|
|
484
549
|
### One step per transaction: `group: :transaction`
|
|
@@ -488,7 +553,7 @@ action shows up as several steps. `group: :transaction` combines steps from the
|
|
|
488
553
|
same database transaction:
|
|
489
554
|
|
|
490
555
|
```ruby
|
|
491
|
-
PaperTrailDiff.
|
|
556
|
+
PaperTrailDiff.analyze(article, associations: [:comments], activity: true, group: :transaction)
|
|
492
557
|
```
|
|
493
558
|
|
|
494
559
|
- A combined step compares the state before the transaction with the state after
|
|
@@ -508,11 +573,13 @@ PaperTrailDiff.activity_timeline(article, associations: [:comments], group: :tra
|
|
|
508
573
|
the savepoint keeps one group.
|
|
509
574
|
- A step joins only the group of the step just before it. Two transactions
|
|
510
575
|
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
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
576
|
+
interleave, each form a group for every run of their own versions. A
|
|
577
|
+
transaction's changes to associated records are read once it has ended
|
|
578
|
+
(see [version order](#version-order)), so they appear in the group of its
|
|
579
|
+
last run; the changes its root versions record appear in their own runs.
|
|
580
|
+
- Also accepted by `analyze_many` and `analyze_scope` with `activity: true`,
|
|
581
|
+
and by `report`, which groups by default when given `associations:` (pass
|
|
582
|
+
`group: nil` to turn it off).
|
|
516
583
|
|
|
517
584
|
Without grouping, a step inside a transaction can look empty. A child's new
|
|
518
585
|
value is only visible at the next recorded event, and inside a transaction that
|
|
@@ -527,7 +594,9 @@ A step's `diff` holds only what changed. To show unchanged fields too, such as
|
|
|
527
594
|
a comment's author next to an edited comment body, keep the snapshots:
|
|
528
595
|
|
|
529
596
|
```ruby
|
|
530
|
-
steps = PaperTrailDiff.
|
|
597
|
+
steps = PaperTrailDiff.analyze(
|
|
598
|
+
article, associations: [:comments], activity: true, snapshots: true
|
|
599
|
+
).activity_timeline
|
|
531
600
|
|
|
532
601
|
step = steps.reject(&:empty?).last
|
|
533
602
|
step.from_snapshot.associations["comments"].records.first.attributes["author"]
|
|
@@ -537,21 +606,22 @@ step.from_snapshot.associations["comments"].records.first.attributes["author"]
|
|
|
537
606
|
do use memory, because each one contains every chosen association.
|
|
538
607
|
- `from_snapshot` is `nil` for a step starting at a `create` version, because the
|
|
539
608
|
record did not exist yet.
|
|
540
|
-
- Also accepted by `
|
|
541
|
-
|
|
609
|
+
- Also accepted by `analyze_many` and `analyze_scope` with `activity: true`,
|
|
610
|
+
and by `report`.
|
|
542
611
|
- [`net_changes`](#net-changes) reads them, so it needs this option.
|
|
543
612
|
|
|
544
|
-
### What each event recorded
|
|
613
|
+
### What each event recorded
|
|
545
614
|
|
|
546
|
-
A step's `diff` compares the state before and after an event.
|
|
547
|
-
|
|
548
|
-
|
|
615
|
+
A step's `diff` compares the state before and after an event. Its boundaries
|
|
616
|
+
also carry what PaperTrail
|
|
617
|
+
[stored with each version](#what-a-version-recorded), such as for an audit
|
|
618
|
+
log:
|
|
549
619
|
|
|
550
620
|
<!-- executable:reference-step-sources -->
|
|
551
621
|
```ruby
|
|
552
|
-
steps = PaperTrailDiff.
|
|
553
|
-
article, associations: [:comments],
|
|
554
|
-
)
|
|
622
|
+
steps = PaperTrailDiff.analyze(
|
|
623
|
+
article, associations: [:comments], activity: true, group: :transaction
|
|
624
|
+
).activity_timeline
|
|
555
625
|
|
|
556
626
|
steps.reject(&:empty?).flat_map(&:sources).map do |source|
|
|
557
627
|
{
|
|
@@ -574,10 +644,14 @@ end
|
|
|
574
644
|
for the whole call, however many steps or records share the version. Read
|
|
575
645
|
them from the boundary rather than calling `PaperTrailDiff.recorded_changes`
|
|
576
646
|
for its version, which decodes it again each time.
|
|
577
|
-
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
647
|
+
- `to_h(metadata: true)` includes them on each boundary and source, which
|
|
648
|
+
decodes every version's changes.
|
|
649
|
+
- `recorded_changes: false` leaves them unread: a boundary's
|
|
650
|
+
`recorded_changes` then raises `ConfigurationError` instead of returning
|
|
651
|
+
`nil`, `to_h(metadata: true)` leaves them out, and
|
|
652
|
+
[change rows](#change-rows) credit a field's whole change to the last of
|
|
653
|
+
its record's versions. The boundaries of a root `timeline`, built without
|
|
654
|
+
`activity: true`, never read them.
|
|
581
655
|
- Names in `ignore:`, or in `ignore: { all: }`, are left out. So are names
|
|
582
656
|
ignored on the root path, `"$"`, for the root's own versions. Names ignored
|
|
583
657
|
on an association path are not left out, because a child's version does not
|
|
@@ -602,85 +676,18 @@ A `within:` window whose last change is the deletion ends the same way, and the
|
|
|
602
676
|
`diff` of an `analyze` over that window ends at "no record". Removing a chosen
|
|
603
677
|
child is reported as `removed` in its parent's association.
|
|
604
678
|
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
`
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
the range at a version instead (see the
|
|
611
|
-
[checkpoint recipe](#saving-a-checkpoint)), or use a join model with
|
|
612
|
-
`has_many :through`.
|
|
613
|
-
|
|
614
|
-
PT-AT records HABTM members under the transaction a version was saved in, and
|
|
615
|
-
does not say which record they belong to. If another record with a HABTM of the
|
|
616
|
-
same name, such as a second article, also saved a version in that transaction
|
|
617
|
-
and members were recorded there, reading the root's membership at that version
|
|
618
|
-
raises `IncompleteAssociationHistoryError` instead of mixing both records'
|
|
619
|
-
members. Save each HABTM owner's versions in a transaction of its own.
|
|
620
|
-
|
|
621
|
-
PT-AT records membership only when the owner saves a version, so the gem knows
|
|
622
|
-
it only at root versions. A change made between two root versions is reported
|
|
623
|
-
in the first step after the earlier one, and credited to that step's source:
|
|
624
|
-
usually the earlier root version, which someone else may have saved. A member
|
|
625
|
-
created between them is reported in the step that starts with its creation
|
|
626
|
-
instead. A change attached before a checkpoint is therefore credited to
|
|
627
|
-
whoever saved the version before the checkpoint, not to the checkpoint's
|
|
628
|
-
author. To credit a change to the person who made it, save a checkpoint just
|
|
629
|
-
before the change as well as after it: the step between the two checkpoints is
|
|
630
|
-
theirs.
|
|
631
|
-
|
|
632
|
-
PT-AT works out the membership a version records from the instance that saves
|
|
633
|
-
it: the instance's current members, with the changes that instance made undone,
|
|
634
|
-
so that the version holds the membership from before its own event. It never
|
|
635
|
-
forgets those changes, not even on `reload`. Only the first version an instance
|
|
636
|
-
saves after changing a HABTM is right; each later save from it records the
|
|
637
|
-
membership from before that change again. The gem then reports the change late,
|
|
638
|
-
or reports a member that never left as removed and added again. Load the record
|
|
639
|
-
again, with `find`, before saving it a second time, and save checkpoints from a
|
|
640
|
-
freshly loaded record, as the [checkpoint recipe](#saving-a-checkpoint) does.
|
|
641
|
-
|
|
642
|
-
## analyze
|
|
679
|
+
With `activity: true` and associations, the deletion is reported in the
|
|
680
|
+
window its transaction ends in, like any other change. So a window after the
|
|
681
|
+
`destroy` version can still report it, when the transaction went on saving
|
|
682
|
+
other records, and a window after that transaction's end reports nothing: an
|
|
683
|
+
empty timeline and an empty diff.
|
|
643
684
|
|
|
644
|
-
|
|
645
|
-
|
|
646
|
-
|
|
647
|
-
|
|
648
|
-
|
|
649
|
-
|
|
650
|
-
analysis.diff # net change over the range
|
|
651
|
-
analysis.timeline # the same steps timeline returns
|
|
652
|
-
analysis.activity_timeline # nil unless activity: true
|
|
653
|
-
analysis.from_snapshot # the full state at the start (nil before creation)
|
|
654
|
-
analysis.to_snapshot # the full state at the end
|
|
655
|
-
analysis.window # the time window it covers, or nil without within:
|
|
656
|
-
analysis.to_h(snapshots: true, metadata: true)
|
|
657
|
-
```
|
|
658
|
-
|
|
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.
|
|
672
|
-
- When nothing in the range is reported, the analysis is empty: an empty
|
|
673
|
-
`diff` and timelines, and `nil` for `from_snapshot` and `to_snapshot`. Here
|
|
674
|
-
`nil` means no state was read, not that the record did not exist; reading
|
|
675
|
-
one would rebuild the record's whole graph, a cost per record in a batch.
|
|
676
|
-
Use `compare` with a version and the record to see a state that did not
|
|
677
|
-
change.
|
|
678
|
-
- `activity: true` also builds the activity timeline. `snapshots:`, `group:`,
|
|
679
|
-
and `recorded_changes:` apply to the activity timeline and require
|
|
680
|
-
`activity: true`.
|
|
681
|
-
- Options: `from:`, `to:`, `within:`, `associations:`, `ignore:`, `activity:`,
|
|
682
|
-
`version_scope:`, `snapshots:`, `group:`, `recorded_changes:`,
|
|
683
|
-
`allow_approximate:`.
|
|
685
|
+
A record restored afterwards under its id, as saving `version.reify` does,
|
|
686
|
+
is the same root before and after. A range that ends at its `destroy` then
|
|
687
|
+
ends before the deletion, as at any other version, and the range from the
|
|
688
|
+
`destroy` reports the removal, in its step to the version that restored it,
|
|
689
|
+
so the two report it once. The transaction that restored it is the root's
|
|
690
|
+
from its first event, as for a record created afresh.
|
|
684
691
|
|
|
685
692
|
## Reports for many records
|
|
686
693
|
|
|
@@ -708,7 +715,7 @@ results.fetch(["Order", order.id.to_s]).diff
|
|
|
708
715
|
are `nil` (see [analyze](#analyze)).
|
|
709
716
|
- Records must be saved and unique.
|
|
710
717
|
- Options: `within:`, `associations:`, `ignore:`, `activity:`, `version_scope:`,
|
|
711
|
-
`snapshots:`, `group:`, `recorded_changes
|
|
718
|
+
`snapshots:`, `group:`, `recorded_changes:`.
|
|
712
719
|
|
|
713
720
|
### analyze_scope
|
|
714
721
|
|
|
@@ -727,6 +734,7 @@ report.analyses # { identity => Analysis } for records that still exist
|
|
|
727
734
|
report.roots # the selected records, in relation order
|
|
728
735
|
report.unreachable # identities of selected records that no longer exist
|
|
729
736
|
report.deleted # { identity => Analysis or nil }, with include_deleted: true
|
|
737
|
+
report.total # how many existing records the relation selects, before its limit and offset
|
|
730
738
|
|
|
731
739
|
report.roots.each do |order|
|
|
732
740
|
report.analysis_for(order) # its Analysis, without building the identity
|
|
@@ -735,8 +743,8 @@ end
|
|
|
735
743
|
analyses, unreachable = report # destructures into analyses and unreachable
|
|
736
744
|
```
|
|
737
745
|
|
|
738
|
-
It takes the same options as `analyze_many`, plus `limit
|
|
739
|
-
`
|
|
746
|
+
It takes the same options as `analyze_many`, plus `limit:` and
|
|
747
|
+
`include_deleted:`. `within:` can be omitted to use
|
|
740
748
|
all history.
|
|
741
749
|
|
|
742
750
|
### report
|
|
@@ -749,8 +757,13 @@ report = PaperTrailDiff.report(Article.all, since: 1.day.ago, limit: 100)
|
|
|
749
757
|
```
|
|
750
758
|
|
|
751
759
|
It accepts `associations:`, `ignore:`, `version_scope:`, `snapshots:`, `group:`,
|
|
752
|
-
`recorded_changes:`, `include_deleted
|
|
753
|
-
|
|
760
|
+
`recorded_changes:`, and `include_deleted:`.
|
|
761
|
+
|
|
762
|
+
With `associations:`, `report` groups by transaction unless told otherwise:
|
|
763
|
+
each save of a record and its associated records is one step, as with
|
|
764
|
+
[`group: :transaction`](#one-step-per-transaction-group-transaction). Pass
|
|
765
|
+
`group: nil` for a step per version. A report without `associations:` is not
|
|
766
|
+
grouped.
|
|
754
767
|
|
|
755
768
|
### Which records are selected
|
|
756
769
|
|
|
@@ -763,14 +776,14 @@ and `allow_approximate:`.
|
|
|
763
776
|
versions and cannot show a change to its associations alone, so only a
|
|
764
777
|
record's own version selects it. With
|
|
765
778
|
[`version_scope:`](#reporting-only-some-changes-version_scope), only the
|
|
766
|
-
versions the filter keeps select it, the record's own and its associations'
|
|
779
|
+
versions the filter keeps select it, the record's own and its associations',
|
|
780
|
+
each with its whole transaction when associations are requested.
|
|
767
781
|
- **An analysis can still be empty.** A record is selected by any version on its
|
|
768
782
|
paths, but its analysis compares only the state you requested. A join row
|
|
769
783
|
whose role changed, or a version that touched only ignored columns, selects a
|
|
770
784
|
record with nothing to report.
|
|
771
785
|
- **A relation checks current values.** `Order.where(status: "open")` means open
|
|
772
|
-
now, not open during the window.
|
|
773
|
-
values.
|
|
786
|
+
now, not open during the window.
|
|
774
787
|
- **`limit:` is a safety ceiling, not a page size.** If more records are
|
|
775
788
|
selected, the call raises `BatchLimitExceededError` instead of returning part
|
|
776
789
|
of the answer. Narrow the relation or the window, or raise the limit.
|
|
@@ -781,16 +794,33 @@ and `allow_approximate:`.
|
|
|
781
794
|
as sorting by the ID when it names the column, alone or after the table's
|
|
782
795
|
name, as `order("title, id")` does. Give the queries that show the page the
|
|
783
796
|
same tie-breaker, such as `order(:status, :id)`, so that they list the
|
|
784
|
-
records the report analyzed.
|
|
797
|
+
records the report analyzed. `total` counts the records the relation selects before
|
|
798
|
+
its `limit` and `offset`, for a pager's "page 2 of 6"; a paged relation
|
|
799
|
+
takes one more statement for it. A relation grouped by another column
|
|
800
|
+
counts its groups. Deleted records are not counted. If a join repeats a record, it is analyzed
|
|
785
801
|
once, in order of first appearance. A relation grouped by anything but the
|
|
786
802
|
ID, such as `select("MAX(id) AS id").group(:author_id)`, keeps its own
|
|
787
803
|
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)
|
|
804
|
+
It needs one that tells its groups apart, such as `order(:author_id)`;
|
|
805
|
+
without any order it raises `ConfigurationError`.
|
|
789
806
|
- Selection still scans the versions in the window, so keep windows reasonable
|
|
790
807
|
for large tables. Each requested association adds one query per level, however
|
|
791
808
|
many records it selects. Changes to associations are found from PT-AT's
|
|
792
809
|
`version_associations`, so history recorded before PT-AT was installed selects
|
|
793
|
-
nothing
|
|
810
|
+
nothing, and neither does a `belongs_to` target's change for a record that
|
|
811
|
+
has no version of its own, such as one created with PaperTrail turned off:
|
|
812
|
+
`analyze` on that record reports the change, but no selection finds it.
|
|
813
|
+
The same holds below the root: a product renamed does not select an order
|
|
814
|
+
whose line item has no version, over `line_items.product`, nor a tag
|
|
815
|
+
renamed an order whose join row has none, over a `has_many :through`. After
|
|
816
|
+
adding PaperTrail to existing data, every row is in this state until it is
|
|
817
|
+
next saved. A
|
|
818
|
+
change below a `has_many` or `has_one` child that has no version selects
|
|
819
|
+
the owner its row names now, since such a child has held that key
|
|
820
|
+
throughout, as an analysis reads it.
|
|
821
|
+
- **A window with associations reads from where the transactions open at
|
|
822
|
+
its start began**, and selects by the versions those transactions saved
|
|
823
|
+
before it, but by no other version saved before the start.
|
|
794
824
|
|
|
795
825
|
### Deleted records
|
|
796
826
|
|
|
@@ -807,8 +837,9 @@ is not paginated.
|
|
|
807
837
|
as it stood when it was destroyed, and keeps only those that match. So a report
|
|
808
838
|
on `Article.where(account_id: account.id)` returns that account's deletions,
|
|
809
839
|
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](#
|
|
811
|
-
must, ranges
|
|
840
|
+
model's own columns, as a [readable association scope's](#association-scopes)
|
|
841
|
+
must, ranges and equality on a date or a time included; anything else, such
|
|
842
|
+
as a join or SQL text, raises
|
|
812
843
|
`ConfigurationError`. `Article.none` keeps none. Its order, limit, and offset
|
|
813
844
|
are ignored here, since they choose a page of existing rows. A record whose
|
|
814
845
|
destroy PaperTrail did not record has no state to test and stays listed.
|
|
@@ -828,53 +859,7 @@ step's `diff.record_presence_change.from` is the record just before it was
|
|
|
828
859
|
deleted, even when it was also created inside the window, where
|
|
829
860
|
`from_snapshot` is `nil`.
|
|
830
861
|
|
|
831
|
-
###
|
|
832
|
-
|
|
833
|
-
`historical_filter:` selects records by values they had at any point in the
|
|
834
|
-
window. For example, to find articles that were titled `"Published"` at some
|
|
835
|
-
point in the last day, including ones published during it:
|
|
836
|
-
|
|
837
|
-
```ruby
|
|
838
|
-
report = PaperTrailDiff.report(
|
|
839
|
-
Article.all, since: 1.day.ago, limit: 100,
|
|
840
|
-
historical_filter: { title: "Published" }
|
|
841
|
-
)
|
|
842
|
-
```
|
|
843
|
-
|
|
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
|
|
849
|
-
hash, every key must be equal (`==`) once both sides are cast to the
|
|
850
|
-
attribute's type, as `where` casts its values: `{ status: :published }` matches
|
|
851
|
-
an enum, and a date or time matches whether the history stored it as YAML or
|
|
852
|
-
as a string in a `json` column. Values are read from the stored history
|
|
853
|
-
without calling `reify`, and unknown or unrecorded attributes raise an error
|
|
854
|
-
instead of matching `nil`. For other checks, pass a callable such as
|
|
855
|
-
`->(article) { article.title.start_with?("Pub") }`; it receives each state as a
|
|
856
|
-
model instance and may run queries of its own.
|
|
857
|
-
|
|
858
|
-
- It looks only at the record itself, not its associations, and does not check
|
|
859
|
-
whether a value was held for the whole window.
|
|
860
|
-
- Only the history of records the relation selects is read, and the relation's
|
|
861
|
-
order, `limit`, and `offset` then page the ones that match. Deleted records,
|
|
862
|
-
which a relation cannot test, are read too, and those that match are listed
|
|
863
|
-
in `unreachable`.
|
|
864
|
-
- Matching records the relation selects count toward `limit:`, and matching
|
|
865
|
-
stops as soon as the limit is exceeded. Matching deleted records count only
|
|
866
|
-
with `include_deleted: true`, as without a filter.
|
|
867
|
-
- `max_filter_versions:` limits how many versions the filter loads, including
|
|
868
|
-
the one version after the window it reads for each record, and the versions
|
|
869
|
-
of deleted records. The default is 10,000. Going over raises
|
|
870
|
-
`FilterLimitExceededError` before the extra batch is checked. It does not
|
|
871
|
-
limit queries inside a callable.
|
|
872
|
-
- `version_scope:` narrows which changes are reported, not which states are
|
|
873
|
-
tested here.
|
|
874
|
-
- It is accepted by `analyze_scope` and `report`, which select records from a
|
|
875
|
-
relation.
|
|
876
|
-
|
|
877
|
-
### Costly associations
|
|
862
|
+
### Association scopes
|
|
878
863
|
|
|
879
864
|
Most associations are loaded for all records together. That includes an
|
|
880
865
|
association whose scope, or whose target's default scope, is plain conditions
|
|
@@ -895,13 +880,21 @@ boolean, and enum columns, with SQL's rules for NULL. A `nil` test
|
|
|
895
880
|
scope such as `where(deleted_at: nil)` is read too. String and text columns
|
|
896
881
|
are read only on SQLite and PostgreSQL, and only without a column collation:
|
|
897
882
|
MySQL and SQL Server compare strings without regard to case or trailing spaces
|
|
898
|
-
by default, which the gem cannot repeat
|
|
899
|
-
`
|
|
883
|
+
by default, which the gem cannot repeat. Neither is PostgreSQL's `citext`,
|
|
884
|
+
which ignores case, nor its `character(n)`, which pads with spaces.
|
|
885
|
+
|
|
886
|
+
The gem lists the SQL column types it reads this way for each of SQLite,
|
|
887
|
+
PostgreSQL, MySQL (`mysql2` and `trilogy`), and SQL Server. A condition or
|
|
888
|
+
order on a column of any other type, or on another adapter, is not read,
|
|
889
|
+
like the scopes described below. On SQL Server a `datetime2` is read but not
|
|
890
|
+
a legacy `datetime` or `smalldatetime`, which round the times they store.
|
|
900
891
|
|
|
901
892
|
Ranges, such as `where(position: 2..)` or `where(created_at: 1.day.ago...)`,
|
|
902
893
|
and Arel's `gt`, `gteq`, `lt`, and `lteq`, are read on the columns an order
|
|
903
894
|
can sort by, below: integer, integer enum, date, and datetime columns, with
|
|
904
|
-
the same conditions on a datetime's precision.
|
|
895
|
+
the same conditions on a datetime's precision. Equality and `IN` on a date or a
|
|
896
|
+
datetime column, such as `where(due_on: Date.current)`, are read under those
|
|
897
|
+
conditions too.
|
|
905
898
|
|
|
906
899
|
A `limit` or `offset`, and the order of a `has_one`, are read the same way
|
|
907
900
|
when the order is total and the gem can repeat it:
|
|
@@ -937,35 +930,31 @@ comment that meets the part's conditions, not only the latest. Its own `limit`
|
|
|
937
930
|
or `offset` ranks the rows the join yields, so a record reached through two
|
|
938
931
|
join records fills two places, as in the query. A `has_one :through` whose
|
|
939
932
|
own scope or whose parts have a limit, an offset, or a `has_one` order is not
|
|
940
|
-
read.
|
|
933
|
+
read. One without an order reads, as Active Record does, the target of its
|
|
934
|
+
first join row by key.
|
|
941
935
|
|
|
942
936
|
The gem cannot read the rest: a `limit` or `offset` whose order is not total or
|
|
943
937
|
sorts by another column type (strings follow a collation) or by a datetime
|
|
944
938
|
history cannot rank exactly, scopes that take the owner
|
|
945
939
|
(`->(article) { ... }`), scopes written as SQL strings, ranges on other column
|
|
946
940
|
types, scopes that join or select, and conditions on other column types or
|
|
947
|
-
other tables, such as a string column on MySQL.
|
|
948
|
-
|
|
949
|
-
members, swapping in their older versions, and never checks the scope against
|
|
950
|
-
them. A record that entered the scope since is reported as a member it was
|
|
951
|
-
not, so a comment moved into `-> { where("position > 2") }`, or restored from
|
|
952
|
-
a soft delete, shows as changed rather than added.
|
|
941
|
+
other tables, such as a string column on MySQL. Who met such a scope at a
|
|
942
|
+
past point cannot be told from stored versions.
|
|
953
943
|
|
|
954
944
|
So every method that reads history raises `UnsupportedAssociationError` for
|
|
955
|
-
such a path and names it. Remove it from `associations:`, rewrite its scope
|
|
956
|
-
plain conditions on the target's own columns
|
|
957
|
-
|
|
958
|
-
|
|
959
|
-
and needs no opt-in.
|
|
945
|
+
such a path and names it. Remove it from `associations:`, or rewrite its scope
|
|
946
|
+
as plain conditions on the target's own columns. A comparison of two current
|
|
947
|
+
records reads no history and accepts any scope. A composite foreign key is
|
|
948
|
+
refused the same way: association history is recorded by a single id.
|
|
960
949
|
|
|
961
950
|
A polymorphic `belongs_to` is loaded together too, with one query per target
|
|
962
951
|
class. Its classes are known only from the records, though, so batch methods
|
|
963
|
-
cannot reject one with a scope they cannot read in advance: a
|
|
964
|
-
points at such a class
|
|
965
|
-
polymorphic `belongs_to` itself is rejected.
|
|
952
|
+
cannot reject one with a default scope they cannot read in advance: reading a
|
|
953
|
+
record that points at such a class raises `UnsupportedAssociationError`. A
|
|
954
|
+
scope on the polymorphic `belongs_to` itself is rejected.
|
|
966
955
|
|
|
967
956
|
This check covers known association cases only. Your model callbacks, custom
|
|
968
|
-
attribute types
|
|
957
|
+
attribute types can still run queries. See the
|
|
969
958
|
[performance guide](performance.md) for measurements.
|
|
970
959
|
|
|
971
960
|
## Associations
|
|
@@ -981,18 +970,27 @@ diff = PaperTrailDiff.compare(from, to, associations: [:author, "comments.replie
|
|
|
981
970
|
(`associations: :comments`) or hashes of names to what to include below them
|
|
982
971
|
(`associations: [:author, { comments: :replies }]`).
|
|
983
972
|
|
|
984
|
-
Supported: `belongs_to`, `has_one`, `has_many` (including `:through`)
|
|
985
|
-
`has_and_belongs_to_many
|
|
973
|
+
Supported: `belongs_to`, `has_one`, and `has_many` (including `:through`).
|
|
974
|
+
A `has_and_belongs_to_many` is not: see
|
|
975
|
+
[replacing a has_and_belongs_to_many](#replacing-a-has_and_belongs_to_many).
|
|
976
|
+
Associated models must use `has_paper_trail`, the
|
|
977
|
+
target of a `has_one` or `has_many` must declare the `belongs_to` back, and
|
|
986
978
|
historical states need PT-AT installed and enabled
|
|
987
979
|
(`PaperTrail.config.track_associations = true`). The gem never follows
|
|
988
980
|
associations you did not ask for, so cyclic models are safe.
|
|
989
981
|
|
|
982
|
+
When more than one record points at the owner of a `has_one` without an
|
|
983
|
+
order, history reads the one with the lowest primary key, as Active Record's
|
|
984
|
+
`LIMIT 1` does on SQLite, MySQL, and SQL Server. PostgreSQL promises no order
|
|
985
|
+
there, so its current record can read another one: give such a `has_one` an
|
|
986
|
+
order, or a unique index, to make the choice the same everywhere.
|
|
987
|
+
|
|
990
988
|
How each kind is reported:
|
|
991
989
|
|
|
992
990
|
| Association | Record replaced, added, or removed | Same record, fields changed |
|
|
993
991
|
| --- | --- | --- |
|
|
994
992
|
| `belongs_to`, `has_one` | `relationship` (a `ValueChange` of snapshots) | `changed` |
|
|
995
|
-
| `has_many
|
|
993
|
+
| `has_many` | `added`, `removed` (snapshots) | `changed` (`RecordChange`) |
|
|
996
994
|
|
|
997
995
|
```ruby
|
|
998
996
|
diff.associations["author"].relationship # from one author to another
|
|
@@ -1019,8 +1017,7 @@ comments.changed.first.associations["replies"].added
|
|
|
1019
1017
|
names no class, such as one a renamed model left in its versions, raises
|
|
1020
1018
|
`IncompleteAssociationHistoryError` naming the record.
|
|
1021
1019
|
- `has_many :through` uses the versioned join model's history, so join-model
|
|
1022
|
-
attributes are available.
|
|
1023
|
-
attributes; it has no join model, so it has no join attributes.
|
|
1020
|
+
attributes are available.
|
|
1024
1021
|
- A `has_many :through` holds, at each point, the records the owner reached
|
|
1025
1022
|
through the join records it had then. A record that moves to another join
|
|
1026
1023
|
record leaves one owner and joins the other, and so does every record under
|
|
@@ -1036,24 +1033,11 @@ comments.changed.first.associations["replies"].added
|
|
|
1036
1033
|
model with no versions, so the through cannot be rebuilt from history.
|
|
1037
1034
|
Replace the HABTM with a `has_many :through` a versioned join model to
|
|
1038
1035
|
compare it. `association_paths` leaves such a through out.
|
|
1039
|
-
- A
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
|
|
1044
|
-
`UnsupportedAssociationError` up front in every method, even when the path
|
|
1045
|
-
leads back to the root, as `"comments.article.tags"` does.
|
|
1046
|
-
`association_paths` leaves such a path out. To follow another record's
|
|
1047
|
-
memberships, compare that record's own checkpoints, or replace the HABTM
|
|
1048
|
-
with a `has_many :through` a versioned join model.
|
|
1049
|
-
- A HABTM with a scope, such as `-> { where(active: true) }`, or whose target
|
|
1050
|
-
has a default scope, raises `UnsupportedAssociationError` up front in every
|
|
1051
|
-
method. PT-AT records a HABTM's members by loading the association through
|
|
1052
|
-
its scope when the owner saves, so a target outside the scope then is never
|
|
1053
|
-
recorded, and one that enters the scope before the owner's next save is a
|
|
1054
|
-
member history cannot show. Replace it with a `has_many :through` a
|
|
1055
|
-
versioned join model, which can be scoped. `association_paths` leaves it
|
|
1056
|
-
out.
|
|
1036
|
+
- A `has_and_belongs_to_many` raises `UnsupportedAssociationError` up front
|
|
1037
|
+
in every method, wherever it is in a path, and `association_paths` leaves
|
|
1038
|
+
it out. Its join rows have no versions, so nothing records when a member
|
|
1039
|
+
joined or left. See
|
|
1040
|
+
[replacing a has_and_belongs_to_many](#replacing-a-has_and_belongs_to_many).
|
|
1057
1041
|
- An association keyed on a column other than a primary key, such as
|
|
1058
1042
|
`has_many :comments, primary_key: :legacy_id`, raises
|
|
1059
1043
|
`UnsupportedAssociationError` up front in every method, and so does a
|
|
@@ -1061,22 +1045,75 @@ comments.changed.first.associations["replies"].added
|
|
|
1061
1045
|
pointed at by that record's ID, so history read that way would show other
|
|
1062
1046
|
records' children. `association_paths` leaves it out. Naming the primary key
|
|
1063
1047
|
itself, `primary_key: :id`, is accepted.
|
|
1048
|
+
- A `has_many` or `has_one` whose target declares no `belongs_to` on its
|
|
1049
|
+
foreign key, such as `has_many :comments` when `Comment` has no
|
|
1050
|
+
`belongs_to :article`, raises `UnsupportedAssociationError` up front in
|
|
1051
|
+
every method, and so does a `has_many :through` with such a part. PT-AT
|
|
1052
|
+
records a record's owner on the record's own versions, once for each
|
|
1053
|
+
`belongs_to` it declares, so with none nothing says a comment that was
|
|
1054
|
+
destroyed or moved away was ever the article's. `association_paths` leaves
|
|
1055
|
+
it out. Declare the `belongs_to` to request the path; versions saved before
|
|
1056
|
+
then recorded no owner, so a record that left before then is not reported.
|
|
1064
1057
|
- A root that uses single-table inheritance gets the associations of the
|
|
1065
1058
|
class it had at each version, so you can request one that only a subclass
|
|
1066
1059
|
declares. Without an `item_subtype` column, PaperTrail stores only the base
|
|
1067
1060
|
class; the gem reads the subclass from the type column the version stored.
|
|
1068
1061
|
A version where the record was a class without that association raises
|
|
1069
1062
|
`UnknownAssociationError`, as a current record of that class would. A
|
|
1070
|
-
stored type that names no class raises `InvalidEndpointError`.
|
|
1063
|
+
stored type that names no class raises `InvalidEndpointError`. A child's
|
|
1064
|
+
`belongs_to` may name any class of the owner's table: PT-AT records the
|
|
1065
|
+
class it names, and the gem looks for each one the target declares.
|
|
1071
1066
|
- Requesting associations for a historical state without PT-AT raises
|
|
1072
1067
|
`AssociationTrackingUnavailableError`. Unknown names raise
|
|
1073
1068
|
`UnknownAssociationError`; unsupported macros raise
|
|
1074
1069
|
`UnsupportedAssociationError`.
|
|
1075
1070
|
|
|
1071
|
+
### Replacing a has_and_belongs_to_many
|
|
1072
|
+
|
|
1073
|
+
A `has_and_belongs_to_many` keeps its members in a join table with no model,
|
|
1074
|
+
so PaperTrail saves no version when one joins or leaves. Give the join table
|
|
1075
|
+
a model with `has_paper_trail`, and read the association with
|
|
1076
|
+
`has_many :through`:
|
|
1077
|
+
|
|
1078
|
+
```ruby
|
|
1079
|
+
class AddIdToArticlesTags < ActiveRecord::Migration[7.1]
|
|
1080
|
+
def change
|
|
1081
|
+
add_column :articles_tags, :id, :primary_key # a version names its row by id
|
|
1082
|
+
end
|
|
1083
|
+
end
|
|
1084
|
+
|
|
1085
|
+
class Tagging < ApplicationRecord
|
|
1086
|
+
self.table_name = "articles_tags"
|
|
1087
|
+
belongs_to :article
|
|
1088
|
+
belongs_to :tag
|
|
1089
|
+
has_paper_trail
|
|
1090
|
+
end
|
|
1091
|
+
|
|
1092
|
+
class Article < ApplicationRecord
|
|
1093
|
+
has_many :taggings, dependent: :destroy
|
|
1094
|
+
has_many :tags, through: :taggings, dependent: :destroy
|
|
1095
|
+
has_paper_trail
|
|
1096
|
+
end
|
|
1097
|
+
```
|
|
1098
|
+
|
|
1099
|
+
`article.tags`, `article.tags << tag`, and `article.tag_ids = ids` work as
|
|
1100
|
+
before. Two things differ:
|
|
1101
|
+
|
|
1102
|
+
- `dependent: :destroy` on the `has_many :through` is what records a member
|
|
1103
|
+
leaving. Without it, `article.tags.delete(tag)` and `tag_ids=` delete the
|
|
1104
|
+
join row without callbacks, so no version is saved and history cannot
|
|
1105
|
+
show when the member left.
|
|
1106
|
+
- Members that joined before the change have no `create` version, so they
|
|
1107
|
+
read as members from before history began, like any
|
|
1108
|
+
[record created without a version](#how-papertrail-stores-history).
|
|
1109
|
+
|
|
1110
|
+
Request `associations: [:tags]` for the members, or `["taggings.tag"]` to
|
|
1111
|
+
read the join rows' own attributes too.
|
|
1112
|
+
|
|
1076
1113
|
### Saving a checkpoint
|
|
1077
1114
|
|
|
1078
1115
|
Sometimes you want a version of the root record without changing it, for
|
|
1079
|
-
example to fix the end of a report
|
|
1116
|
+
example to fix the end of a report. Save one
|
|
1080
1117
|
inside a transaction on a freshly loaded record, and turn off PaperTrail's
|
|
1081
1118
|
timestamp synchronization for that model so the version records the time it
|
|
1082
1119
|
was saved:
|
|
@@ -1094,17 +1131,7 @@ end
|
|
|
1094
1131
|
```
|
|
1095
1132
|
|
|
1096
1133
|
Without `synchronize_version_creation_timestamp: false`, the checkpoint takes the
|
|
1097
|
-
record's old `updated_at` as its time and lands in the past.
|
|
1098
|
-
transaction: HABTM membership cannot be read from a transaction in which
|
|
1099
|
-
another record with the same HABTM also saved a version (see the
|
|
1100
|
-
[HABTM limitation](#habtm-limitation)). A checkpoint records membership as it
|
|
1101
|
-
is when saved, including a member attached or created earlier in the same
|
|
1102
|
-
transaction. A change it captures is credited to the step before it, so its
|
|
1103
|
-
author is whoever saved the version before the checkpoint, unless that is a
|
|
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.
|
|
1134
|
+
record's old `updated_at` as its time and lands in the past.
|
|
1108
1135
|
|
|
1109
1136
|
### Files from ActiveStorage
|
|
1110
1137
|
|
|
@@ -1288,18 +1315,20 @@ Which version a row names:
|
|
|
1288
1315
|
- A field's change names the version of the row's own record that made it,
|
|
1289
1316
|
among those its step's transaction saved. Inside a transaction, a record's
|
|
1290
1317
|
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
|
|
1292
|
-
|
|
1293
|
-
|
|
1294
|
-
the
|
|
1318
|
+
version opens; the row still names its own record's version: the one that
|
|
1319
|
+
recorded the field's new value. With `recorded_changes: false`, the gem
|
|
1320
|
+
cannot tell which of a record's versions made the change, so the row names
|
|
1321
|
+
the last of them.
|
|
1295
1322
|
- A record created or destroyed names its `create` or `destroy`. Its fields
|
|
1296
1323
|
name the version that recorded each value: the `create`, or a later save in
|
|
1297
|
-
the same step. A record that joined or left
|
|
1298
|
-
|
|
1299
|
-
|
|
1300
|
-
|
|
1301
|
-
|
|
1302
|
-
|
|
1324
|
+
the same step. A record that joined or left by its own update, such as a
|
|
1325
|
+
comment moved to another article, names the last of its versions in the
|
|
1326
|
+
step's transaction. A record that joined or left through another record's
|
|
1327
|
+
change, such as a new `belongs_to` target, names the step's
|
|
1328
|
+
`source_boundary`.
|
|
1329
|
+
|
|
1330
|
+
A change PaperTrail did not record gets a row of its own, unless
|
|
1331
|
+
`recorded_changes: false` is passed: a write [saved without a version](#how-papertrail-stores-history),
|
|
1303
1332
|
such as `update_columns`. Its source has kind `:unversioned` and names the
|
|
1304
1333
|
record, with no version, event, author, or time, so `to_h` has `nil` for
|
|
1305
1334
|
`version_id`, `event`, `whodunnit`, `recorded_at`, and `transaction_id`. A
|
|
@@ -1311,7 +1340,7 @@ recorded, leave such rows out:
|
|
|
1311
1340
|
<!-- executable:reference-unversioned-rows -->
|
|
1312
1341
|
```ruby
|
|
1313
1342
|
analysis = PaperTrailDiff.analyze(
|
|
1314
|
-
article, associations: [:comments], activity: true
|
|
1343
|
+
article, associations: [:comments], activity: true
|
|
1315
1344
|
)
|
|
1316
1345
|
|
|
1317
1346
|
analysis.change_rows.reject(&:unversioned?)
|
|
@@ -1338,13 +1367,12 @@ without a version undid, leaving the field as it was, has no row.
|
|
|
1338
1367
|
`net_changes` folds change rows into one entry per record: its fields before
|
|
1339
1368
|
the rows a block keeps, and its fields with only their changes made. This
|
|
1340
1369
|
example keeps the rows with an author. A write saved without a version has
|
|
1341
|
-
none, so
|
|
1370
|
+
none, so it is left out:
|
|
1342
1371
|
|
|
1343
1372
|
<!-- executable:reference-net-changes -->
|
|
1344
1373
|
```ruby
|
|
1345
1374
|
analysis = PaperTrailDiff.analyze(
|
|
1346
|
-
article, associations: [:comments], activity: true, snapshots: true
|
|
1347
|
-
recorded_changes: true
|
|
1375
|
+
article, associations: [:comments], activity: true, snapshots: true
|
|
1348
1376
|
)
|
|
1349
1377
|
|
|
1350
1378
|
changes = analysis.net_changes { |row| row.source.whodunnit }
|
|
@@ -1407,7 +1435,8 @@ PaperTrailDiff.nested_changes(from_value, to_value) # also accepts two values
|
|
|
1407
1435
|
are strings. Values are reported as they were given.
|
|
1408
1436
|
- Arrays are compared by their elements, not positions. An `ArrayChange` has
|
|
1409
1437
|
`added`, `removed`, and `reordered?`, plus the whole `from` and `to`. Objects
|
|
1410
|
-
inside arrays are compared whole.
|
|
1438
|
+
inside arrays are compared whole. Elements match as values under a key do,
|
|
1439
|
+
so `1` and `1.0` are different elements.
|
|
1411
1440
|
- A missing key is `PaperTrailDiff::NestedComparator::ABSENT`, not `nil`, because
|
|
1412
1441
|
`{"a": null}` and `{}` are different.
|
|
1413
1442
|
- Two arrays at the top, as a `json` column can hold, return one `ArrayChange`
|
|
@@ -1448,7 +1477,8 @@ Other details:
|
|
|
1448
1477
|
`{}`.
|
|
1449
1478
|
- `ignore:` takes an array of attribute names and defaults to `updated_at`, as
|
|
1450
1479
|
elsewhere. It does not take `paths:`, because a version does not say which
|
|
1451
|
-
association path it was reached through. Primary keys are left out
|
|
1480
|
+
association path it was reached through. Primary keys are left out, and so
|
|
1481
|
+
is a name the model no longer has, such as a column dropped since.
|
|
1452
1482
|
- Unlike PaperTrail's `version.changeset`, it never loads the record. That
|
|
1453
1483
|
saves a query per version, and a deleted record's values keep their types,
|
|
1454
1484
|
such as an enum's label rather than the integer PaperTrail stored.
|
|
@@ -1457,16 +1487,15 @@ Other details:
|
|
|
1457
1487
|
[JSON history](#history-stored-as-json), times keep the digits history
|
|
1458
1488
|
stores and binary and `serialize`d values read as JSON stored them.
|
|
1459
1489
|
|
|
1460
|
-
|
|
1461
|
-
versions
|
|
1462
|
-
|
|
1463
|
-
[what each event recorded](#what-each-event-recorded-recorded_changes-true):
|
|
1490
|
+
Activity steps need no such call. Each step's sources carry what their
|
|
1491
|
+
versions recorded, with no extra queries; see
|
|
1492
|
+
[what each event recorded](#what-each-event-recorded):
|
|
1464
1493
|
|
|
1465
1494
|
<!-- executable:reference-recorded-changes -->
|
|
1466
1495
|
```ruby
|
|
1467
|
-
steps = PaperTrailDiff.
|
|
1468
|
-
article, associations: [:comments],
|
|
1469
|
-
)
|
|
1496
|
+
steps = PaperTrailDiff.analyze(
|
|
1497
|
+
article, associations: [:comments], activity: true
|
|
1498
|
+
).activity_timeline
|
|
1470
1499
|
|
|
1471
1500
|
steps.last.source_boundary.recorded_changes
|
|
1472
1501
|
```
|
|
@@ -1485,14 +1514,14 @@ Each descriptor has `path`, `kind`, `target_type`, `through`, `polymorphic`,
|
|
|
1485
1514
|
and `cycle`. Cycles are marked and not followed.
|
|
1486
1515
|
|
|
1487
1516
|
Only associations a request accepts are listed, so each path can be passed to
|
|
1488
|
-
`associations:`. The PaperTrail versions association, a
|
|
1489
|
-
|
|
1517
|
+
`associations:`. The PaperTrail versions association, a
|
|
1518
|
+
`has_and_belongs_to_many`, a `has_many :through` that goes through one, an
|
|
1490
1519
|
association keyed on a column other than a primary key, one whose ends keep
|
|
1491
1520
|
their versions in different tables, and one whose target, or a model its
|
|
1492
1521
|
`has_many :through` goes through, has no `has_paper_trail` are left out. A path
|
|
1493
|
-
history
|
|
1494
|
-
|
|
1495
|
-
[
|
|
1522
|
+
with a scope history cannot read, such as one written as SQL text, is listed,
|
|
1523
|
+
since a comparison of two current records accepts it; a request that reads
|
|
1524
|
+
history refuses it (see [association scopes](#association-scopes)). A `has_many :through` Active
|
|
1496
1525
|
Record cannot follow, such as one through a polymorphic `belongs_to`, raises
|
|
1497
1526
|
Active Record's own error from any model discovery reaches, as requesting it
|
|
1498
1527
|
does.
|
|
@@ -1502,7 +1531,7 @@ association history. They are what `compare` takes: two versions, or a version
|
|
|
1502
1531
|
and the current record.
|
|
1503
1532
|
|
|
1504
1533
|
```ruby
|
|
1505
|
-
report = PaperTrailDiff.diagnose(from_version, article, associations: [:
|
|
1534
|
+
report = PaperTrailDiff.diagnose(from_version, article, associations: [:author, "comments.replies"])
|
|
1506
1535
|
|
|
1507
1536
|
report.ok? # no errors among the checks that ran
|
|
1508
1537
|
report.errors.map(&:code)
|
|
@@ -1513,9 +1542,9 @@ Association checks run only for requested associations. The version-order check
|
|
|
1513
1542
|
always runs. Every reason `compare` would refuse the same request is an error,
|
|
1514
1543
|
with the message `compare` would raise, so `ok?` is false whenever `compare`
|
|
1515
1544
|
would refuse: an unknown or unsupported association, missing association
|
|
1516
|
-
tracking, an unversioned target, or a path
|
|
1517
|
-
|
|
1518
|
-
|
|
1545
|
+
tracking, an unversioned target, or a path history cannot read. Endpoints `compare` rejects whatever their history holds,
|
|
1546
|
+
such as versions given newest first, two records, or an unsaved record, raise
|
|
1547
|
+
the error `compare` raises. `ok?` does not prove the history is complete.
|
|
1519
1548
|
|
|
1520
1549
|
## Models, schemas, and edge cases
|
|
1521
1550
|
|
|
@@ -1528,17 +1557,52 @@ warning instead. `ok?` does not prove the history is complete.
|
|
|
1528
1557
|
- **Custom version classes** (`has_paper_trail versions: { class_name: }`) are
|
|
1529
1558
|
supported. For association history, a model and each association you ask
|
|
1530
1559
|
for must keep their versions, and their PT-AT version associations, in the
|
|
1531
|
-
same tables. PT-AT reads an association's history from its owner's
|
|
1532
|
-
|
|
1533
|
-
|
|
1534
|
-
|
|
1535
|
-
|
|
1536
|
-
|
|
1560
|
+
same tables. PT-AT reads an association's history from its owner's
|
|
1561
|
+
tables, so it cannot follow an association into a different version
|
|
1562
|
+
table. Such an association raises `UnsupportedAssociationError` naming
|
|
1563
|
+
both tables, and `association_paths` leaves it out. One custom table
|
|
1564
|
+
shared by the models works like PaperTrail's own.
|
|
1565
|
+
|
|
1566
|
+
PaperTrail numbers a transaction by the id of the first version it
|
|
1567
|
+
saved, in whichever table that was, so with more than one version table
|
|
1568
|
+
two transactions can share a number. Where a [time window](#time-windows)
|
|
1569
|
+
looks for the start of a transaction, the gem tells them apart by the
|
|
1570
|
+
version each began with, which carries its own id as its number. It
|
|
1571
|
+
consults the version classes loaded at the time, in the model's
|
|
1572
|
+
database: load them eagerly, as production does, or name them before
|
|
1573
|
+
reading. It cannot tell two apart when the earlier one's first version
|
|
1574
|
+
has been deleted, or when both ran at the same time. Within the history
|
|
1575
|
+
of one record and its associations, versions are still grouped by number
|
|
1576
|
+
alone, so where two transactions of one number both saved them, their
|
|
1577
|
+
versions are read as one transaction's: one step, or one group, runs from
|
|
1578
|
+
the first of them to the last, and the changes of every step between are
|
|
1579
|
+
reported inside it. In a young database both tables count from 1, so
|
|
1580
|
+
such numbers are common there. The version a transaction began with also
|
|
1581
|
+
marks where it began only when it is dated first: with a second version
|
|
1582
|
+
table, a callback that saves other records before its own version (see
|
|
1583
|
+
[version order](#version-order)) can make a window read that transaction
|
|
1584
|
+
as two.
|
|
1537
1585
|
- **A scoped versions association** (`has_paper_trail versions: { scope: }`)
|
|
1538
1586
|
does not change what is read: every method reads all of a record's
|
|
1539
1587
|
versions, because a history replayed without some of them would credit
|
|
1540
1588
|
their changes to the next version kept. To report only some changes, pass
|
|
1541
1589
|
[`version_scope:`](#reporting-only-some-changes-version_scope).
|
|
1590
|
+
- **Values the database rounds.** PaperTrail stores the value a record held
|
|
1591
|
+
in memory, and the database may have stored less of it. The gem compares
|
|
1592
|
+
every side in the form the database keeps: times to the column's precision
|
|
1593
|
+
(a SQL Server `datetime` to 1/300 s, read back to the millisecond), a MySQL
|
|
1594
|
+
`float` to single precision, a SQLite decimal as the number SQLite returns,
|
|
1595
|
+
and a fixed-width `char` column padded (PostgreSQL, SQL Server) or with its
|
|
1596
|
+
trailing spaces stripped (MySQL). So saving `12:00:00.1234567` to a column
|
|
1597
|
+
that keeps microseconds is not reported as a change. A date assigned to a
|
|
1598
|
+
datetime column, which Active Record leaves on the instance when time zone
|
|
1599
|
+
aware attributes are off or `update_columns` writes it, is read as
|
|
1600
|
+
midnight in Active Record's default time zone, as the database stores it.
|
|
1601
|
+
A `serialize`d hash in a `json` or `jsonb` history keeps string keys only
|
|
1602
|
+
(see [history stored as JSON](#history-stored-as-json)).
|
|
1603
|
+
- **Attributes without a column**, such as one declared with `attribute` for
|
|
1604
|
+
a form, are left out of every diff, snapshot and change row. PaperTrail
|
|
1605
|
+
stores whatever the instance held for one, but no row holds it.
|
|
1542
1606
|
|
|
1543
1607
|
### Version order
|
|
1544
1608
|
|
|
@@ -1547,6 +1611,8 @@ works when IDs increase with each insert, as autoincrement IDs do, in one
|
|
|
1547
1611
|
table. UUID version IDs do not, and models with their own version tables count
|
|
1548
1612
|
IDs separately, so two such versions with the same timestamp cannot be ordered;
|
|
1549
1613
|
the gem raises `AmbiguousVersionOrderError` naming both instead of guessing.
|
|
1614
|
+
That includes a tie for the first version after a `within:` window, which
|
|
1615
|
+
holds the state the window ends in.
|
|
1550
1616
|
Timestamps stored to the second, as on a MySQL `datetime` column, make ties
|
|
1551
1617
|
common. `diagnose` reports this as an error.
|
|
1552
1618
|
|
|
@@ -1563,6 +1629,14 @@ with `inverted_version_order`. Set the option on models whose `updated_at`
|
|
|
1563
1629
|
your application sets, and correct the stored `created_at` of versions
|
|
1564
1630
|
already saved.
|
|
1565
1631
|
|
|
1632
|
+
The versions of different records in one transaction can be dated out of
|
|
1633
|
+
the order they were saved in too: a callback or nested save that a model
|
|
1634
|
+
declares before `has_paper_trail` saves other records' versions first and
|
|
1635
|
+
the model's own last, dated as its save began. A transaction takes effect at
|
|
1636
|
+
its latest dated version, ids breaking a tie, and a window reads it as open
|
|
1637
|
+
across its start when it has versions dated on both sides, so its changes
|
|
1638
|
+
are reported once whichever version it saved last.
|
|
1639
|
+
|
|
1566
1640
|
`created_at` comes from your application server's clock. A clock that jumps
|
|
1567
1641
|
backwards, or servers whose clocks disagree, can record a later change with an
|
|
1568
1642
|
earlier time. Keep server clocks synchronized.
|
|
@@ -1574,26 +1648,31 @@ can therefore show a state the database never held, and a result for an earlier
|
|
|
1574
1648
|
version or a closed window can change once that transaction commits.
|
|
1575
1649
|
[Time windows](#time-windows) explains how to settle a report.
|
|
1576
1650
|
|
|
1651
|
+
Two transactions that save in one record's tree at the same time interleave
|
|
1652
|
+
their versions. Each version was saved while the other transaction's changes
|
|
1653
|
+
were not yet committed, so at a version of one, a record the other saved
|
|
1654
|
+
reads as it stood before the other began, as a record the version's own
|
|
1655
|
+
transaction saved does. A version reads so wherever it is used: in
|
|
1656
|
+
`compare`, and as the start or the end of a range. The other's changes appear from the event after its
|
|
1657
|
+
last version, in a step it opens, so a record it changed and changed back,
|
|
1658
|
+
such as a comment it created and deleted again, appears in no step and in no
|
|
1659
|
+
window's starting state or diff. A transaction is open from its first
|
|
1660
|
+
version on the requested paths in the range, or from the range's start when
|
|
1661
|
+
it began before it, to the latest dated version it saved of any record in
|
|
1662
|
+
the same version table. Row locks keep the two from saving the same
|
|
1663
|
+
record.
|
|
1664
|
+
|
|
1577
1665
|
Association changes between versions with the same timestamp are placed using
|
|
1578
|
-
the same order.
|
|
1579
|
-
uses timestamps only: a path history reads only approximately, which takes
|
|
1580
|
-
`allow_approximate: true`, a composite foreign key, and a polymorphic
|
|
1581
|
-
`belongs_to` whose target's default scope history cannot read. The
|
|
1582
|
-
[architecture notes](architecture.md) list them. When a request includes such a
|
|
1583
|
-
path, or any polymorphic `belongs_to`, whose targets are known only per record,
|
|
1584
|
-
`diagnose` warns about tied timestamps and a comparison between two tied
|
|
1585
|
-
versions emits the `ambiguous_association_boundary.paper_trail_diff`
|
|
1586
|
-
notification. Recording timestamps below one second avoids the problem. On SQL Server, PT-AT compares
|
|
1587
|
-
those timestamps only to about 3 milliseconds (a `datetime` tick, 1/300 s),
|
|
1588
|
-
because the adapter writes the times in its queries that way, so for these
|
|
1589
|
-
shapes two versions saved closer together than that may be read in the wrong
|
|
1590
|
-
order.
|
|
1666
|
+
the same order.
|
|
1591
1667
|
|
|
1592
1668
|
### History stored as JSON
|
|
1593
1669
|
|
|
1594
1670
|
PaperTrail's JSON serializer, and a `json` or `jsonb` `object` column, store
|
|
1595
1671
|
times to milliseconds by default (`ActiveSupport::JSON::Encoding.time_precision`).
|
|
1596
|
-
|
|
1672
|
+
The gem reads the digits from what the history's writer writes, a serializer
|
|
1673
|
+
of your own that wraps the JSON one included, so the legacy JSON format,
|
|
1674
|
+
which writes whole seconds, keeps whole seconds. For those histories the gem
|
|
1675
|
+
compares all times at that precision, so an
|
|
1597
1676
|
unchanged timestamp is not reported as changed. A change smaller than that
|
|
1598
1677
|
precision was never recorded and cannot be reported. A `json` or `jsonb`
|
|
1599
1678
|
column also returns times and dates as strings, which PaperTrail leaves as
|
|
@@ -1627,9 +1706,9 @@ If you change `created_at` after saving instead, change every version saved
|
|
|
1627
1706
|
in the same transaction, not only the ones you check. PT-AT gives all of
|
|
1628
1707
|
them the same `transaction_id`, including versions of other models saved by
|
|
1629
1708
|
callbacks. A version left at the time the test ran makes that transaction
|
|
1630
|
-
seem to last from your chosen time until today.
|
|
1631
|
-
|
|
1632
|
-
|
|
1709
|
+
seem to last from your chosen time until today. The transaction is then
|
|
1710
|
+
reported where it ends, today (see [Time windows](#time-windows)), and a window
|
|
1711
|
+
around your chosen time loses the changes the test expects.
|
|
1633
1712
|
|
|
1634
1713
|
```ruby
|
|
1635
1714
|
def set_version_time(version, time)
|
|
@@ -1645,12 +1724,11 @@ subscribe to:
|
|
|
1645
1724
|
|
|
1646
1725
|
- `compare.paper_trail_diff`
|
|
1647
1726
|
- `compare_many.paper_trail_diff`
|
|
1648
|
-
- `
|
|
1727
|
+
- `analyze.paper_trail_diff` (includes `step_count`, the length of
|
|
1728
|
+
`activity_timeline` with `activity: true` and of `timeline` without)
|
|
1649
1729
|
- `analyze_many.paper_trail_diff`
|
|
1650
1730
|
- `load_live_endpoints.paper_trail_diff`
|
|
1651
1731
|
- `prepare_history.paper_trail_diff`
|
|
1652
|
-
- `ambiguous_association_boundary.paper_trail_diff`
|
|
1653
|
-
- `moved_window.paper_trail_diff`, when a [window edge moves](#time-windows)
|
|
1654
1732
|
|
|
1655
1733
|
```ruby
|
|
1656
1734
|
ActiveSupport::Notifications.subscribe(/\.paper_trail_diff\z/) do |name, start, finish, _id, payload|
|
|
@@ -1673,39 +1751,74 @@ All errors inherit from `PaperTrailDiff::Error`.
|
|
|
1673
1751
|
|
|
1674
1752
|
| Error | Raised when |
|
|
1675
1753
|
| --- | --- |
|
|
1676
|
-
| `ConfigurationError` | An option is invalid |
|
|
1677
|
-
| `InvalidEndpointError` | A record is unsaved, destroyed, or has unsaved changes, or `recorded_changes` is given something other than a version |
|
|
1754
|
+
| `ConfigurationError` | An option is invalid, or the version class has no `object` column to read states from |
|
|
1755
|
+
| `InvalidEndpointError` | A record is unsaved, destroyed, or has unsaved changes, a version was loaded without its `object`, a model has no `has_paper_trail`, or `recorded_changes` is given something other than a version |
|
|
1678
1756
|
| `VersionMismatchError` | Two endpoints belong to different records |
|
|
1679
1757
|
| `ReversedEndpointsError` | Two versions are given newest first |
|
|
1680
|
-
| `InvalidTimelineRangeError` | A range is invalid, for example `within:` with `from:`, or `:last
|
|
1758
|
+
| `InvalidTimelineRangeError` | A range is invalid, for example `within:` with `from:`, or `:last`, or a boundary symbol is unknown |
|
|
1681
1759
|
| `InvalidTimeRangeError` | `within:` is not a range with a beginning, in time order |
|
|
1682
1760
|
| `IncompleteTimeRangeError` | A window's last change has no later version and the record has no saved row to read instead |
|
|
1683
1761
|
| `AmbiguousVersionOrderError` | Versions cannot be ordered (see [version order](#version-order)) |
|
|
1684
1762
|
| `BatchLimitExceededError` | More records are selected than `limit:` allows |
|
|
1685
|
-
| `FilterLimitExceededError` | `historical_filter:` needs more than `max_filter_versions:` |
|
|
1686
1763
|
| `AssociationTrackingUnavailableError` | Association history is requested without PT-AT |
|
|
1687
1764
|
| `UnknownAssociationError` | An association name does not exist |
|
|
1688
|
-
| `UnsupportedAssociationError` | An association's macro is not supported, a path continues past a polymorphic `belongs_to`, a `has_many :through` goes through
|
|
1765
|
+
| `UnsupportedAssociationError` | An association's macro is not supported, a path continues past a polymorphic `belongs_to`, an association is a `has_and_belongs_to_many` or a `has_many :through` that goes through one, an association is keyed on a column other than a primary key, the target of a `has_one` or `has_many` declares no `belongs_to` on its foreign key, an association has a composite foreign key, or history cannot read an [association's scope](#association-scopes) |
|
|
1689
1766
|
| `UnversionedAssociationError` | An association's target model, or a model a `has_many :through` goes through, has no `has_paper_trail`, including the class a polymorphic `belongs_to` names |
|
|
1690
|
-
| `IncompleteAssociationHistoryError` | PT-AT did not record enough to rebuild an association, such as
|
|
1691
|
-
| `UnsupportedLiveActivityError` | A HABTM activity range ends at the current record |
|
|
1767
|
+
| `IncompleteAssociationHistoryError` | PT-AT did not record enough to rebuild an association, such as a polymorphic type that names no class |
|
|
1692
1768
|
| `AmbiguousNestedKeyError` | `nested_changes` finds keys like `:a` and `"a"` together |
|
|
1693
1769
|
|
|
1770
|
+
## What results rest on
|
|
1771
|
+
|
|
1772
|
+
Every result is one of three kinds. Knowing which tells you how far to trust
|
|
1773
|
+
it for an audit.
|
|
1774
|
+
|
|
1775
|
+
**Recorded.** PaperTrail stored it, and the gem reads it back: a record's
|
|
1776
|
+
attributes at each version, each version's event, author, and time, and the
|
|
1777
|
+
changes a version [recorded](#what-a-version-recorded). A
|
|
1778
|
+
[change row](#change-rows) credited to a version is one that version
|
|
1779
|
+
recorded.
|
|
1780
|
+
|
|
1781
|
+
**Rebuilt by a stated rule.** PaperTrail did not store it, so the gem derives
|
|
1782
|
+
it the same way every time:
|
|
1783
|
+
|
|
1784
|
+
- *Where a transaction takes effect.* PaperTrail records which versions one
|
|
1785
|
+
transaction saved, not when it committed. The gem places a transaction at
|
|
1786
|
+
the last version it saved, and reports it whole there; see
|
|
1787
|
+
[time windows](#time-windows). Two transactions that overlapped are
|
|
1788
|
+
reported in the order of their last versions, which is usually, but not
|
|
1789
|
+
provably, the order they committed in.
|
|
1790
|
+
- *The order of versions saved in the same instant.* By id; see
|
|
1791
|
+
[version order](#version-order).
|
|
1792
|
+
- *Who was in an association.* PaperTrail stores no membership. The gem
|
|
1793
|
+
reads each candidate's foreign key, and the columns of a
|
|
1794
|
+
[scope](#association-scopes), from its own versions at that point.
|
|
1795
|
+
- *Which record an unordered `has_one` holds* when several match: the one
|
|
1796
|
+
with the lowest primary key.
|
|
1797
|
+
- *A write saved without a version*, such as `update_columns`. It is seen
|
|
1798
|
+
only in the state the next version stores, so it appears in the step of
|
|
1799
|
+
the record's previous recorded change. Its change row is marked
|
|
1800
|
+
`unversioned?`, with no author or time, since none was recorded.
|
|
1801
|
+
|
|
1802
|
+
**Refused.** Where neither holds, a call raises instead of estimating: an
|
|
1803
|
+
association [scope](#association-scopes) history cannot read, a composite
|
|
1804
|
+
foreign key, a `has_and_belongs_to_many`, an unversioned target, or versions
|
|
1805
|
+
that cannot be ordered. No result is an approximation.
|
|
1806
|
+
|
|
1694
1807
|
## Limitations
|
|
1695
1808
|
|
|
1696
1809
|
Results can only be as complete as the history PaperTrail and PT-AT recorded.
|
|
1697
1810
|
|
|
1698
1811
|
- Changes made with versioning off, with `update_columns`, or to `skip:` columns
|
|
1699
1812
|
were never recorded. The first two still appear, in the step for the record's
|
|
1700
|
-
previous recorded change and
|
|
1813
|
+
previous recorded change, and their [change rows](#change-rows) are marked
|
|
1814
|
+
`unversioned?`; see
|
|
1701
1815
|
[how PaperTrail stores history](#how-papertrail-stores-history).
|
|
1702
1816
|
- Deleted versions, schema changes, and serializer changes can affect how old
|
|
1703
1817
|
versions read.
|
|
1704
1818
|
- With PaperTrail's default YAML serializer, PaperTrail 16 and 17 decode a
|
|
1705
1819
|
`time` (time of day) column as `nil`, in `reify` and `changeset` alike,
|
|
1706
1820
|
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,
|
|
1708
|
-
the records it passes to a callable `historical_filter:`, but your own
|
|
1821
|
+
zone is UTC. The gem reads the time each version recorded, but your own
|
|
1709
1822
|
calls to those PaperTrail methods still return `nil`. PaperTrail's JSON
|
|
1710
1823
|
serializer, and SQL Server, whose adapter stores a time its own way, are
|
|
1711
1824
|
not affected. Snapshots and diffs show every time of day on 2000-01-01 in
|
|
@@ -1731,26 +1844,14 @@ Results can only be as complete as the history PaperTrail and PT-AT recorded.
|
|
|
1731
1844
|
- A savepoint that rolls back, or another transaction saving in the same tree
|
|
1732
1845
|
at the same time, can split one transaction into several transaction groups;
|
|
1733
1846
|
see [one step per transaction group](#one-step-per-transaction-group-transaction).
|
|
1734
|
-
-
|
|
1735
|
-
|
|
1736
|
-
|
|
1737
|
-
|
|
1738
|
-
|
|
1739
|
-
|
|
1740
|
-
|
|
1741
|
-
|
|
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).
|
|
1745
|
-
- HABTM membership history exists only where PT-AT recorded it in a
|
|
1746
|
-
transaction, and only for the root record without a scope: a scoped HABTM,
|
|
1747
|
-
or one below the root, raises `UnsupportedAssociationError`, and a transaction that another record with
|
|
1748
|
-
that HABTM also saved a version in raises `IncompleteAssociationHistoryError`. HABTM changes cannot become their own
|
|
1749
|
-
activity steps.
|
|
1750
|
-
- PT-AT has its own
|
|
1751
|
-
[limitations](https://github.com/westonganger/paper_trail-association_tracking#limitations),
|
|
1752
|
-
especially for some `has_one` histories. The gem follows PT-AT's configured
|
|
1753
|
-
error behavior.
|
|
1847
|
+
- A transaction that saves in two version tables is read in each as far as
|
|
1848
|
+
its versions there: where it ends is read from one version table at a time.
|
|
1849
|
+
- A `has_and_belongs_to_many` has no history to read; see
|
|
1850
|
+
[replacing a has_and_belongs_to_many](#replacing-a-has_and_belongs_to_many).
|
|
1851
|
+
- The gem reads the rows PT-AT records with each version to find the records
|
|
1852
|
+
an association held, and rebuilds every state itself. PT-AT's own
|
|
1853
|
+
[limitations](https://github.com/westonganger/paper_trail-association_tracking#limitations)
|
|
1854
|
+
apply to what it records, not to its reifier, which the gem does not use.
|
|
1754
1855
|
- Deep association paths cost more to rebuild. Request only what you need.
|
|
1755
1856
|
|
|
1756
1857
|
Read PaperTrail's
|