paper_trail_diff 0.13.0 → 0.14.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 +318 -0
- data/QUICKSTART.md +9 -6
- data/README.md +84 -9
- data/docs/architecture.md +32 -9
- data/docs/performance.md +106 -13
- data/docs/reference.md +242 -29
- data/docs/testing.md +55 -9
- data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
- data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
- data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
- data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
- data/lib/paper_trail_diff/activity_range.rb +14 -2
- data/lib/paper_trail_diff/activity_relationship.rb +12 -0
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
- data/lib/paper_trail_diff/activity_timeline_builder.rb +30 -24
- data/lib/paper_trail_diff/activity_version_collector.rb +31 -20
- data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
- data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
- data/lib/paper_trail_diff/association_discovery.rb +8 -13
- data/lib/paper_trail_diff/association_traversal.rb +169 -45
- data/lib/paper_trail_diff/batch_safety.rb +23 -15
- data/lib/paper_trail_diff/batched_root_versions.rb +21 -39
- data/lib/paper_trail_diff/collection_comparator.rb +18 -20
- data/lib/paper_trail_diff/collection_identity_index.rb +8 -12
- data/lib/paper_trail_diff/comparison_batch.rb +37 -10
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +36 -17
- data/lib/paper_trail_diff/diagnostics.rb +26 -8
- data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
- data/lib/paper_trail_diff/errors.rb +2 -1
- data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +32 -2
- data/lib/paper_trail_diff/historical_filter.rb +12 -17
- data/lib/paper_trail_diff/historical_snapshot_store.rb +6 -9
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +35 -2
- data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
- data/lib/paper_trail_diff/paper_trail_adapter.rb +22 -6
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +1 -1
- data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
- data/lib/paper_trail_diff/prepared_edge_loader.rb +29 -45
- data/lib/paper_trail_diff/prepared_history.rb +63 -54
- data/lib/paper_trail_diff/prepared_history_loader.rb +33 -43
- data/lib/paper_trail_diff/prepared_record_index.rb +26 -0
- data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
- data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
- data/lib/paper_trail_diff/recorded_changes.rb +83 -0
- data/lib/paper_trail_diff/recorded_class.rb +53 -0
- data/lib/paper_trail_diff/root_version_plan.rb +10 -1
- data/lib/paper_trail_diff/scope_condition.rb +331 -0
- data/lib/paper_trail_diff/scope_ranking.rb +196 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
- data/lib/paper_trail_diff/scoped_root_selection.rb +93 -43
- data/lib/paper_trail_diff/snapshot.rb +5 -1
- data/lib/paper_trail_diff/snapshot_normalizer.rb +50 -47
- data/lib/paper_trail_diff/support.rb +9 -4
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -1
- data/lib/paper_trail_diff/time_range.rb +9 -13
- data/lib/paper_trail_diff/time_version_range.rb +6 -6
- data/lib/paper_trail_diff/timeline_range.rb +5 -4
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
- data/lib/paper_trail_diff/version_query.rb +9 -1
- data/lib/paper_trail_diff/version_range.rb +8 -15
- data/lib/paper_trail_diff/version_scope_filter.rb +11 -3
- data/lib/paper_trail_diff.rb +31 -2
- data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
- data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
- data/sig/generated/paper_trail_diff/activity_range.rbs +6 -2
- data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +11 -5
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +10 -4
- data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
- data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +3 -5
- data/sig/generated/paper_trail_diff/association_traversal.rbs +84 -9
- data/sig/generated/paper_trail_diff/batch_safety.rbs +10 -4
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -8
- data/sig/generated/paper_trail_diff/collection_comparator.rbs +6 -3
- data/sig/generated/paper_trail_diff/collection_identity_index.rbs +3 -3
- data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +16 -4
- data/sig/generated/paper_trail_diff/diagnostics.rbs +7 -2
- data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
- data/sig/generated/paper_trail_diff/errors.rbs +2 -1
- data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
- data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +6 -6
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +3 -2
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +17 -0
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +5 -0
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
- data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
- data/sig/generated/paper_trail_diff/prepared_history.rbs +33 -22
- data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +15 -0
- data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
- data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
- data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
- data/sig/generated/paper_trail_diff/root_version_plan.rbs +7 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +185 -0
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +117 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +41 -7
- data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +25 -9
- data/sig/generated/paper_trail_diff/support.rbs +5 -2
- data/sig/generated/paper_trail_diff/time_range.rbs +4 -0
- data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
- data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -1
- data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
- data/sig/generated/paper_trail_diff/version_query.rbs +7 -1
- data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -0
- data/sig/generated/paper_trail_diff.rbs +21 -2
- metadata +20 -4
|
@@ -43,12 +43,20 @@ module PaperTrailDiff
|
|
|
43
43
|
end
|
|
44
44
|
end
|
|
45
45
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
46
|
+
# `activity_tree` names the association paths whose changes also select a
|
|
47
|
+
# root, as an activity analysis reports them. Without one, only a root's
|
|
48
|
+
# own versions select it.
|
|
49
|
+
#: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
|
|
50
|
+
def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
|
|
51
|
+
max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil)
|
|
49
52
|
@scope = normalize_scope(scope)
|
|
53
|
+
reject_unversioned!
|
|
50
54
|
@time_range = time_range
|
|
51
55
|
@limit = validate_limit(limit)
|
|
56
|
+
@related = if activity_tree
|
|
57
|
+
AssociationActivitySelection.new(model, tree: activity_tree,
|
|
58
|
+
time_range: time_range)
|
|
59
|
+
end
|
|
52
60
|
@historical_filter = unless historical_filter.nil?
|
|
53
61
|
HistoricalFilter.new(base_class, predicate: historical_filter,
|
|
54
62
|
time_range: time_range, limit: @limit,
|
|
@@ -58,17 +66,11 @@ module PaperTrailDiff
|
|
|
58
66
|
|
|
59
67
|
#: () -> Result
|
|
60
68
|
def call
|
|
61
|
-
|
|
69
|
+
related = @related&.call || []
|
|
70
|
+
queries = subqueries(related)
|
|
71
|
+
return database_selection(queries) if queries
|
|
62
72
|
|
|
63
|
-
|
|
64
|
-
candidates = @historical_filter.call(candidates) if @historical_filter && candidates.any?
|
|
65
|
-
return Result.new(records: [], unreachable: []) if candidates.empty?
|
|
66
|
-
|
|
67
|
-
live = live_ids(candidates)
|
|
68
|
-
Result.new(
|
|
69
|
-
records: selected_records(live),
|
|
70
|
-
unreachable: (candidates - live).map { |id| identity(id) }.freeze
|
|
71
|
-
)
|
|
73
|
+
plucked_selection(versioned_ids | AssociationActivitySelection.values(related).map(&:to_s))
|
|
72
74
|
end
|
|
73
75
|
|
|
74
76
|
private
|
|
@@ -77,38 +79,67 @@ module PaperTrailDiff
|
|
|
77
79
|
# @rbs @time_range: TimeRange?
|
|
78
80
|
# @rbs @limit: Integer
|
|
79
81
|
# @rbs @historical_filter: untyped
|
|
82
|
+
# @rbs @related: AssociationActivitySelection?
|
|
80
83
|
|
|
81
84
|
# Leaves the candidate set in the database. Plucking every root changed in
|
|
82
85
|
# the window would cost memory and a statement proportional to all activity
|
|
83
86
|
# in the window -- not to the relation or `limit:` -- so a report on one
|
|
84
87
|
# record could read every id in a busy table. A subquery keeps the work
|
|
85
88
|
# bounded by what the relation and the deletions actually contain.
|
|
86
|
-
#: () -> Result
|
|
87
|
-
def database_selection
|
|
88
|
-
candidates = window_versions.select(:item_id)
|
|
89
|
+
#: (Array[AssociationActivitySelection::Query]) -> Result
|
|
90
|
+
def database_selection(related)
|
|
91
|
+
candidates = [window_versions.select(:item_id)] + related.map(&:relation)
|
|
92
|
+
missing = (missing_ids + related_missing_ids(related)).uniq.sort
|
|
89
93
|
Result.new(
|
|
90
94
|
records: selected_records(candidates),
|
|
91
|
-
unreachable:
|
|
95
|
+
unreachable: missing.map { |id| identity(id) }.freeze
|
|
96
|
+
)
|
|
97
|
+
end
|
|
98
|
+
|
|
99
|
+
# Comparing in SQL needs every subquery's column to share the key's type.
|
|
100
|
+
#: (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
|
|
101
|
+
def subqueries(related)
|
|
102
|
+
return unless @historical_filter.nil? && comparable_keys?
|
|
103
|
+
|
|
104
|
+
queries = related.grep(AssociationActivitySelection::Query) #: Array[AssociationActivitySelection::Query]
|
|
105
|
+
matching = queries.select { |ids| ids.type == key_type }
|
|
106
|
+
matching if matching.length == related.length
|
|
107
|
+
end
|
|
108
|
+
|
|
109
|
+
#: (Array[String]) -> Result
|
|
110
|
+
def plucked_selection(candidates)
|
|
111
|
+
candidates = @historical_filter.call(candidates) if @historical_filter
|
|
112
|
+
live = live_ids(candidates)
|
|
113
|
+
Result.new(
|
|
114
|
+
records: selected_records([live]),
|
|
115
|
+
unreachable: (candidates - live).sort.map { |id| identity(id) }.freeze
|
|
92
116
|
)
|
|
93
117
|
end
|
|
94
118
|
|
|
95
119
|
# Comparing the two columns in SQL needs them to share a type: PostgreSQL
|
|
96
|
-
# rejects an integer key against a string item_id outright.
|
|
120
|
+
# rejects an integer key against a string item_id outright. A composite
|
|
121
|
+
# key names no single attribute, so it has no type and never matches.
|
|
97
122
|
#: () -> bool
|
|
98
123
|
def comparable_keys?
|
|
99
|
-
|
|
124
|
+
version_class.type_for_attribute('item_id').type == key_type
|
|
125
|
+
end
|
|
126
|
+
|
|
127
|
+
#: () -> Symbol?
|
|
128
|
+
def key_type
|
|
129
|
+
base_class.type_for_attribute(primary_key).type
|
|
130
|
+
end
|
|
100
131
|
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
132
|
+
#: (Array[AssociationActivitySelection::Query]) -> Array[String]
|
|
133
|
+
def related_missing_ids(related)
|
|
134
|
+
live = base_class.unscoped.select(primary_key).arel
|
|
135
|
+
related.flat_map { |ids| ids.missing(live) }.map(&:to_s)
|
|
104
136
|
end
|
|
105
137
|
|
|
106
138
|
# Changed in the window but without a row, found with an anti-join instead
|
|
107
139
|
# of comparing two plucked lists.
|
|
108
140
|
#: () -> Array[String]
|
|
109
141
|
def missing_ids
|
|
110
|
-
|
|
111
|
-
window_versions.where.not(item_id: live).distinct.pluck(:item_id).map(&:to_s).uniq.sort
|
|
142
|
+
window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
|
|
112
143
|
end
|
|
113
144
|
|
|
114
145
|
#: () -> untyped
|
|
@@ -127,16 +158,21 @@ module PaperTrailDiff
|
|
|
127
158
|
raise ConfigurationError, 'scope: must be an ActiveRecord relation or model class'
|
|
128
159
|
end
|
|
129
160
|
|
|
130
|
-
|
|
131
|
-
|
|
161
|
+
scope.all
|
|
162
|
+
end
|
|
163
|
+
|
|
164
|
+
#: () -> void
|
|
165
|
+
def reject_unversioned!
|
|
166
|
+
return if Support.versioned?(model)
|
|
132
167
|
|
|
133
168
|
raise UnversionedAssociationError,
|
|
134
|
-
"scope: #{
|
|
169
|
+
"scope: #{model} is not versioned, so it has no history to select from"
|
|
135
170
|
end
|
|
136
171
|
|
|
172
|
+
# No Integer subclass has instances, so this is `is_a?` by another name.
|
|
137
173
|
#: (Integer) -> Integer
|
|
138
174
|
def validate_limit(limit)
|
|
139
|
-
return limit if limit.
|
|
175
|
+
return limit if limit.instance_of?(Integer) && limit.positive?
|
|
140
176
|
|
|
141
177
|
raise ConfigurationError, 'limit: must be a positive Integer'
|
|
142
178
|
end
|
|
@@ -146,7 +182,7 @@ module PaperTrailDiff
|
|
|
146
182
|
# version table alone so that it does not depend on rows still existing.
|
|
147
183
|
#: () -> Array[String]
|
|
148
184
|
def versioned_ids
|
|
149
|
-
window_versions.distinct.pluck(:item_id).map(&:to_s)
|
|
185
|
+
window_versions.distinct.pluck(:item_id).map(&:to_s)
|
|
150
186
|
end
|
|
151
187
|
|
|
152
188
|
# Which of those candidates still have a row, asked without the relation's
|
|
@@ -161,14 +197,15 @@ module PaperTrailDiff
|
|
|
161
197
|
# Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
|
|
162
198
|
# relation may order by joined columns or select a PostgreSQL json column.
|
|
163
199
|
# Read bounded pages until the relation ends or too many unique roots appear.
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
200
|
+
# Each candidate source is an id list or a subquery; a record matching any
|
|
201
|
+
# of them is selected.
|
|
202
|
+
#: (Array[untyped]) -> Array[untyped]
|
|
203
|
+
def selected_records(candidates)
|
|
204
|
+
relation = candidate_relation(candidates)
|
|
168
205
|
records = {} #: Hash[untyped, untyped]
|
|
169
206
|
consumed = 0
|
|
170
207
|
loop do
|
|
171
|
-
page = record_page(
|
|
208
|
+
page = record_page(relation, consumed)
|
|
172
209
|
page.each { |record| records[record.id] ||= record }
|
|
173
210
|
reject_oversized!(records.length)
|
|
174
211
|
break if page.length < PAGE_SIZE
|
|
@@ -178,15 +215,20 @@ module PaperTrailDiff
|
|
|
178
215
|
records.values.freeze
|
|
179
216
|
end
|
|
180
217
|
|
|
218
|
+
#: (Array[untyped]) -> untyped
|
|
219
|
+
def candidate_relation(candidates)
|
|
220
|
+
candidates.map do |ids|
|
|
221
|
+
conditions = { primary_key => ids } #: Hash[untyped, untyped]
|
|
222
|
+
ordered_scope.where(conditions)
|
|
223
|
+
end.reduce(:or)
|
|
224
|
+
end
|
|
225
|
+
|
|
181
226
|
#: (untyped, Integer) -> Array[untyped]
|
|
182
|
-
def record_page(
|
|
227
|
+
def record_page(relation, consumed)
|
|
183
228
|
count = page_limit(consumed)
|
|
184
229
|
return [] if count.zero?
|
|
185
230
|
|
|
186
|
-
|
|
187
|
-
conditions = { primary_key => live } #: Hash[untyped, untyped]
|
|
188
|
-
ordered_scope.where(conditions)
|
|
189
|
-
.offset((@scope.offset_value || 0) + consumed).limit(count).to_a
|
|
231
|
+
relation.offset((@scope.offset_value || 0) + consumed).limit(count)
|
|
190
232
|
end
|
|
191
233
|
|
|
192
234
|
# Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
|
|
@@ -220,22 +262,30 @@ module PaperTrailDiff
|
|
|
220
262
|
|
|
221
263
|
#: () -> String
|
|
222
264
|
def item_type
|
|
223
|
-
base_class.name
|
|
265
|
+
base_class.name
|
|
266
|
+
end
|
|
267
|
+
|
|
268
|
+
# A relation delegates class methods to its model, so every mutation here,
|
|
269
|
+
# which drops `.model`, answers the same.
|
|
270
|
+
# mutant:disable
|
|
271
|
+
#: () -> untyped
|
|
272
|
+
def model
|
|
273
|
+
@scope.model
|
|
224
274
|
end
|
|
225
275
|
|
|
226
276
|
#: () -> untyped
|
|
227
277
|
def base_class
|
|
228
|
-
|
|
278
|
+
model.base_class
|
|
229
279
|
end
|
|
230
280
|
|
|
231
281
|
#: () -> untyped
|
|
232
282
|
def primary_key
|
|
233
|
-
|
|
283
|
+
model.primary_key
|
|
234
284
|
end
|
|
235
285
|
|
|
236
286
|
#: () -> untyped
|
|
237
287
|
def version_class
|
|
238
|
-
|
|
288
|
+
model.paper_trail.version_class
|
|
239
289
|
end
|
|
240
290
|
end
|
|
241
291
|
end
|
|
@@ -171,7 +171,11 @@ module PaperTrailDiff
|
|
|
171
171
|
|
|
172
172
|
#: (type: String, id: untyped, attributes: snapshot_attributes, ?associations: snapshot_associations) -> void
|
|
173
173
|
def initialize(type:, id:, attributes:, associations: {})
|
|
174
|
-
|
|
174
|
+
unless type.is_a?(String)
|
|
175
|
+
raise ArgumentError, "record type must be a String, not #{type.inspect}"
|
|
176
|
+
end
|
|
177
|
+
|
|
178
|
+
@type = Support.immutable_copy(type)
|
|
175
179
|
@id = Support.immutable_copy(id)
|
|
176
180
|
@identity = [@type, @id].freeze
|
|
177
181
|
@attributes = normalize_hash(attributes)
|
|
@@ -21,9 +21,7 @@ module PaperTrailDiff
|
|
|
21
21
|
#: (String, AssociationSnapshot) -> AssociationSnapshot
|
|
22
22
|
def association(path, snapshot)
|
|
23
23
|
previous = @associations[path]
|
|
24
|
-
|
|
25
|
-
return previous
|
|
26
|
-
end
|
|
24
|
+
return previous if previous && same_association?(previous, snapshot)
|
|
27
25
|
|
|
28
26
|
@associations[path] = snapshot
|
|
29
27
|
end
|
|
@@ -38,10 +36,14 @@ module PaperTrailDiff
|
|
|
38
36
|
left.attributes == right.attributes &&
|
|
39
37
|
left.associations.keys == right.associations.keys &&
|
|
40
38
|
left.associations.all? do |name, association|
|
|
41
|
-
|
|
42
|
-
other && association.kind == other.kind && association.records == other.records
|
|
39
|
+
same_association?(association, right.associations.fetch(name))
|
|
43
40
|
end
|
|
44
41
|
end
|
|
42
|
+
|
|
43
|
+
#: (AssociationSnapshot, AssociationSnapshot) -> bool
|
|
44
|
+
def same_association?(left, right)
|
|
45
|
+
left.kind == right.kind && left.records == right.records
|
|
46
|
+
end
|
|
45
47
|
end
|
|
46
48
|
|
|
47
49
|
# Converts an ActiveRecord graph into immutable, persistence-independent snapshots.
|
|
@@ -53,11 +55,13 @@ module PaperTrailDiff
|
|
|
53
55
|
@traversal = traversal
|
|
54
56
|
@pool = pool
|
|
55
57
|
@structural_columns = {} #: Hash[String, Array[String]]
|
|
56
|
-
@excluded_attributes = {} #: Hash[Array[untyped], Array[String]]
|
|
58
|
+
@excluded_attributes = {} #: Hash[Array[untyped], Array[String?]]
|
|
57
59
|
end
|
|
58
60
|
|
|
59
61
|
#: (untyped, reifier: untyped) -> RecordSnapshot?
|
|
60
62
|
def call(record, reifier:)
|
|
63
|
+
return unless record
|
|
64
|
+
|
|
61
65
|
reflections = reflections_for(record, @tree, '')
|
|
62
66
|
normalize_record(record, @tree, '', reifier, reflections)
|
|
63
67
|
end
|
|
@@ -76,7 +80,7 @@ module PaperTrailDiff
|
|
|
76
80
|
# Normalizes scalar attributes without traversing or loading associations.
|
|
77
81
|
#: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
|
|
78
82
|
def attributes_for(record, tree:, path:)
|
|
79
|
-
if record.
|
|
83
|
+
if record.instance_of?(PreparedRecordState)
|
|
80
84
|
return from_state(record, tree: tree,
|
|
81
85
|
path: path).attributes
|
|
82
86
|
end
|
|
@@ -94,7 +98,7 @@ module PaperTrailDiff
|
|
|
94
98
|
excluded = @excluded_attributes[[model, path]] ||=
|
|
95
99
|
build_excluded_attributes(model, reflections, path)
|
|
96
100
|
snapshot = RecordSnapshot.new(
|
|
97
|
-
type: model.name, id:
|
|
101
|
+
type: model.name, id: state_id(model, state),
|
|
98
102
|
attributes: state.attributes.except(*excluded), associations: associations
|
|
99
103
|
)
|
|
100
104
|
pool_state(path, snapshot)
|
|
@@ -102,6 +106,14 @@ module PaperTrailDiff
|
|
|
102
106
|
|
|
103
107
|
private
|
|
104
108
|
|
|
109
|
+
# The id a live record of the same row reports: one value, or one per
|
|
110
|
+
# column of a composite key.
|
|
111
|
+
#: (untyped, PreparedRecordState) -> untyped
|
|
112
|
+
def state_id(model, state)
|
|
113
|
+
key = model.primary_key
|
|
114
|
+
key.instance_of?(Array) ? state.attributes.fetch_values(*key) : state.attributes.fetch(key)
|
|
115
|
+
end
|
|
116
|
+
|
|
105
117
|
#: (String, RecordSnapshot) -> RecordSnapshot
|
|
106
118
|
def pool_state(path, snapshot)
|
|
107
119
|
path.empty? ? snapshot : @pool.record(path, snapshot)
|
|
@@ -112,12 +124,10 @@ module PaperTrailDiff
|
|
|
112
124
|
# @rbs @traversal: AssociationTraversal
|
|
113
125
|
# @rbs @pool: SnapshotPool
|
|
114
126
|
# @rbs @structural_columns: Hash[String, Array[String]]
|
|
115
|
-
# @rbs @excluded_attributes: Hash[Array[untyped], Array[String]]
|
|
127
|
+
# @rbs @excluded_attributes: Hash[Array[untyped], Array[String?]]
|
|
116
128
|
|
|
117
|
-
#: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
|
|
129
|
+
#: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
|
|
118
130
|
def normalize_record(record, tree, path, reifier, reflections)
|
|
119
|
-
return unless record
|
|
120
|
-
|
|
121
131
|
snapshot = RecordSnapshot.new(
|
|
122
132
|
type: record.class.name,
|
|
123
133
|
id: record.id,
|
|
@@ -129,7 +139,7 @@ module PaperTrailDiff
|
|
|
129
139
|
|
|
130
140
|
#: (untyped, Array[untyped], String) -> snapshot_attributes
|
|
131
141
|
def normalized_attributes(record, reflections, path)
|
|
132
|
-
attributes = record.attributes
|
|
142
|
+
attributes = record.attributes
|
|
133
143
|
excluded_attributes(record, reflections, path).each { |name| attributes.delete(name) }
|
|
134
144
|
StoredTimePrecision.apply(attributes, StoredTimePrecision.digits(record.class))
|
|
135
145
|
end
|
|
@@ -137,23 +147,20 @@ module PaperTrailDiff
|
|
|
137
147
|
# Every input is fixed for one model class at one selected path, and the
|
|
138
148
|
# path's structural columns are recorded before its records normalize, so
|
|
139
149
|
# this is resolved once instead of per record per boundary.
|
|
140
|
-
#: (untyped, Array[untyped], String) -> Array[String]
|
|
150
|
+
#: (untyped, Array[untyped], String) -> Array[String?]
|
|
141
151
|
def excluded_attributes(record, reflections, path)
|
|
142
152
|
model_class = record.class
|
|
143
153
|
@excluded_attributes[[model_class, path]] ||=
|
|
144
154
|
build_excluded_attributes(model_class, reflections, path)
|
|
145
155
|
end
|
|
146
156
|
|
|
147
|
-
#: (untyped, Array[untyped], String) -> Array[String]
|
|
157
|
+
#: (untyped, Array[untyped], String) -> Array[String?]
|
|
148
158
|
def build_excluded_attributes(model_class, reflections, path)
|
|
149
|
-
|
|
150
|
-
primary_keys = primary_key.is_a?(Array) ? primary_key : [primary_key]
|
|
151
|
-
# @type var primary_keys: Array[untyped]
|
|
152
|
-
primary_keys = primary_keys.map { |key| key.to_s } # rubocop:disable Style/SymbolProc
|
|
159
|
+
primary_keys = Array(model_class.primary_key) #: Array[String]
|
|
153
160
|
ignored = @ignore_policy.attributes_for(path)
|
|
154
161
|
structural = @structural_columns.fetch(path, [])
|
|
155
|
-
|
|
156
|
-
relationship_columns(reflections) + structural
|
|
162
|
+
primary_keys + ignored + skipped_columns(model_class) +
|
|
163
|
+
relationship_columns(reflections) + structural
|
|
157
164
|
end
|
|
158
165
|
|
|
159
166
|
# `has_paper_trail skip:` columns are never written to a version, so history
|
|
@@ -163,18 +170,17 @@ module PaperTrailDiff
|
|
|
163
170
|
def skipped_columns(model_class)
|
|
164
171
|
return [] unless Support.versioned?(model_class)
|
|
165
172
|
|
|
166
|
-
|
|
167
|
-
entries.
|
|
168
|
-
|
|
169
|
-
end
|
|
173
|
+
# PaperTrail stores these as strings, or hashes keyed by strings.
|
|
174
|
+
entries = model_class.paper_trail_options.fetch(:skip) #: Array[untyped]
|
|
175
|
+
entries.flat_map { |entry| entry.instance_of?(Hash) ? entry.keys : entry }
|
|
170
176
|
end
|
|
171
177
|
|
|
172
|
-
|
|
178
|
+
# A non-polymorphic reflection has no foreign type, so it adds nil, which
|
|
179
|
+
# excludes nothing.
|
|
180
|
+
#: (Array[untyped]) -> Array[String?]
|
|
173
181
|
def relationship_columns(reflections)
|
|
174
182
|
reflections.select { |reflection| reflection.macro == :belongs_to }.flat_map do |reflection|
|
|
175
|
-
|
|
176
|
-
columns << reflection.foreign_type.to_s if reflection.polymorphic?
|
|
177
|
-
columns
|
|
183
|
+
[reflection.foreign_key, reflection.foreign_type]
|
|
178
184
|
end
|
|
179
185
|
end
|
|
180
186
|
|
|
@@ -182,28 +188,20 @@ module PaperTrailDiff
|
|
|
182
188
|
def normalize_associations(record, tree, path, reifier, reflections)
|
|
183
189
|
reflections.to_h do |reflection|
|
|
184
190
|
name = reflection.name.to_s
|
|
185
|
-
|
|
186
|
-
raise ConfigurationError, "missing traversal subtree: #{name}" unless subtree
|
|
187
|
-
|
|
188
|
-
[name, association_snapshot(record, reflection, subtree, path, reifier)]
|
|
191
|
+
[name, association_snapshot(record, reflection, tree.children.fetch(name), path, reifier)]
|
|
189
192
|
end
|
|
190
193
|
end
|
|
191
194
|
|
|
192
195
|
#: (untyped, untyped, AssociationTree, String, untyped) -> AssociationSnapshot
|
|
193
|
-
def association_snapshot(
|
|
196
|
+
def association_snapshot(
|
|
194
197
|
record,
|
|
195
198
|
reflection,
|
|
196
199
|
subtree,
|
|
197
200
|
path,
|
|
198
201
|
reifier
|
|
199
202
|
)
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
associated.to_a
|
|
203
|
-
else
|
|
204
|
-
Array(associated).compact
|
|
205
|
-
end
|
|
206
|
-
child_path = Support.association_path(path, reflection.name.to_s)
|
|
203
|
+
records = members(record, reflection)
|
|
204
|
+
child_path = Support.association_path(path, reflection.name)
|
|
207
205
|
@structural_columns[child_path] ||= @traversal.incoming_relationship_columns(reflection)
|
|
208
206
|
snapshot = AssociationSnapshot.new(
|
|
209
207
|
kind: reflection.macro,
|
|
@@ -212,12 +210,19 @@ module PaperTrailDiff
|
|
|
212
210
|
@pool.association(child_path, snapshot)
|
|
213
211
|
end
|
|
214
212
|
|
|
213
|
+
# A reified history can hold a member PaperTrail could not rebuild. A
|
|
214
|
+
# through loads a record once per join that reaches it; it is one member,
|
|
215
|
+
# as Active Record compares records by class and id.
|
|
216
|
+
#: (untyped, untyped) -> Array[untyped]
|
|
217
|
+
def members(record, reflection)
|
|
218
|
+
Array(record.public_send(reflection.name)).compact.uniq
|
|
219
|
+
end
|
|
220
|
+
|
|
215
221
|
#: (Array[untyped], AssociationTree, String, untyped) -> Array[RecordSnapshot]
|
|
216
222
|
def normalize_children(records, tree, path, reifier)
|
|
217
|
-
reflections_by_class = {} #: Hash[
|
|
218
|
-
records.
|
|
219
|
-
|
|
220
|
-
reflections = reflections_by_class[type] ||= reflections_for(child, tree, path)
|
|
223
|
+
reflections_by_class = {} #: Hash[untyped, Array[untyped]]
|
|
224
|
+
records.map do |child|
|
|
225
|
+
reflections = reflections_by_class[child.class] ||= reflections_for(child, tree, path)
|
|
221
226
|
reifier.reify(child, reflections) unless reflections.empty?
|
|
222
227
|
normalize_record(child, tree, path, reifier, reflections)
|
|
223
228
|
end
|
|
@@ -225,8 +230,6 @@ module PaperTrailDiff
|
|
|
225
230
|
|
|
226
231
|
#: (untyped, AssociationTree, String) -> Array[untyped]
|
|
227
232
|
def reflections_for(record, tree, path)
|
|
228
|
-
return [] unless record
|
|
229
|
-
|
|
230
233
|
@traversal.reflections_for(record.class, tree, path: path)
|
|
231
234
|
end
|
|
232
235
|
end
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Internal helpers for isolating and serializing values held by result objects.
|
|
6
|
-
module Support
|
|
6
|
+
module Support # rubocop:disable Metrics/ModuleLength
|
|
7
7
|
module_function
|
|
8
8
|
|
|
9
9
|
#: (untyped) -> untyped
|
|
@@ -46,7 +46,12 @@ module PaperTrailDiff
|
|
|
46
46
|
|
|
47
47
|
#: (untyped) -> Array[untyped]
|
|
48
48
|
def chronological_version_key(version)
|
|
49
|
-
|
|
49
|
+
version_key(version.created_at, version.id)
|
|
50
|
+
end
|
|
51
|
+
|
|
52
|
+
#: (untyped, untyped) -> Array[untyped]
|
|
53
|
+
def version_key(created_at, id)
|
|
54
|
+
[created_at, id.to_s.rjust(32, '0')]
|
|
50
55
|
end
|
|
51
56
|
|
|
52
57
|
# Ordering falls back to the id whenever timestamps tie, which recovers the
|
|
@@ -124,9 +129,9 @@ module PaperTrailDiff
|
|
|
124
129
|
raise(ConfigurationError, 'versions have incomparable timestamps')
|
|
125
130
|
end
|
|
126
131
|
|
|
127
|
-
#: (String, String) -> String
|
|
132
|
+
#: (String, String | Symbol) -> String
|
|
128
133
|
def association_path(parent, name)
|
|
129
|
-
parent.empty? ? name : "#{parent}.#{name}"
|
|
134
|
+
parent.empty? ? name.to_s : "#{parent}.#{name}"
|
|
130
135
|
end
|
|
131
136
|
|
|
132
137
|
#: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
|
|
@@ -194,7 +194,6 @@ module PaperTrailDiff
|
|
|
194
194
|
@record,
|
|
195
195
|
root_versions: root_versions,
|
|
196
196
|
tree: @tree,
|
|
197
|
-
traversal: AssociationTraversal.new(@tree),
|
|
198
197
|
prepared: (@snapshotter.activity_index if @snapshotter.respond_to?(:activity_index)),
|
|
199
198
|
range_start: @range.begin_time,
|
|
200
199
|
range_end: range_end || root_versions.last
|
|
@@ -40,8 +40,7 @@ module PaperTrailDiff
|
|
|
40
40
|
|
|
41
41
|
#: (untyped) -> untyped
|
|
42
42
|
def trailing_scope(relation)
|
|
43
|
-
|
|
44
|
-
relation.where(after_end(column))
|
|
43
|
+
relation.where(after_end(relation.arel_table[:created_at]))
|
|
45
44
|
end
|
|
46
45
|
|
|
47
46
|
# Each item's earliest version after the range, keyed by item id. One row
|
|
@@ -49,12 +48,11 @@ module PaperTrailDiff
|
|
|
49
48
|
# the query stays portable; a timestamp tie keeps the lower id.
|
|
50
49
|
#: (untyped) -> Hash[String, untyped]
|
|
51
50
|
def first_trailing_versions(relation)
|
|
52
|
-
table = relation.
|
|
51
|
+
table = relation.arel_table
|
|
53
52
|
first_after = VersionQuery.no_earlier_version(table) do |earlier|
|
|
54
53
|
after_end(earlier[:created_at])
|
|
55
54
|
end
|
|
56
|
-
versions = trailing_scope(relation).where(first_after)
|
|
57
|
-
.reorder(created_at: :asc, id: :asc).to_a
|
|
55
|
+
versions = VersionQuery.chronological(trailing_scope(relation).where(first_after))
|
|
58
56
|
first = {} #: Hash[String, untyped]
|
|
59
57
|
versions.each { |version| first[version.item_id.to_s] ||= version }
|
|
60
58
|
first
|
|
@@ -76,17 +74,15 @@ module PaperTrailDiff
|
|
|
76
74
|
|
|
77
75
|
#: (untyped, boundary: Symbol) -> Time
|
|
78
76
|
def coerce_time(value, boundary:)
|
|
79
|
-
unless value.respond_to?(:to_time)
|
|
80
|
-
raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
|
|
81
|
-
end
|
|
82
|
-
|
|
83
77
|
time_value(value).getutc.freeze
|
|
84
|
-
rescue ArgumentError, NoMethodError, TypeError
|
|
85
|
-
raise InvalidTimeRangeError,
|
|
86
|
-
"`within` #{boundary} must be time-like",
|
|
87
|
-
cause: e
|
|
78
|
+
rescue ArgumentError, NoMethodError, TypeError
|
|
79
|
+
raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
|
|
88
80
|
end
|
|
89
81
|
|
|
82
|
+
# Active Support 8.0 and older warn, once per process, that `to_time` will
|
|
83
|
+
# change on a zoned time, so read zoned values without it. Every branch
|
|
84
|
+
# gives the same instant, so no spec (and no mutation) can tell them apart.
|
|
85
|
+
# mutant:disable
|
|
90
86
|
#: (untyped) -> Time
|
|
91
87
|
def time_value(value)
|
|
92
88
|
return value if value.is_a?(Time)
|
|
@@ -4,18 +4,18 @@
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Selects in-range root versions plus one later reconstruction boundary.
|
|
6
6
|
class TimeVersionRange
|
|
7
|
-
#: (untyped, time_range: TimeRange,
|
|
8
|
-
def initialize(record, time_range:, version_scope
|
|
7
|
+
#: (untyped, time_range: TimeRange, version_scope: untyped, live_endpoint: untyped) -> void
|
|
8
|
+
def initialize(record, time_range:, version_scope:, live_endpoint:)
|
|
9
9
|
@record = record
|
|
10
10
|
@time_range = time_range
|
|
11
11
|
@version_scope = version_scope
|
|
12
12
|
@live_endpoint = live_endpoint
|
|
13
13
|
end
|
|
14
14
|
|
|
15
|
-
#: (
|
|
16
|
-
def select_plan(context_required:
|
|
15
|
+
#: (context_required: bool) -> RootVersionPlan
|
|
16
|
+
def select_plan(context_required:)
|
|
17
17
|
relation = Endpoint.versions(@record)
|
|
18
|
-
in_range = ordered(@time_range.scope(relation)
|
|
18
|
+
in_range = ordered(@time_range.scope(relation))
|
|
19
19
|
RootVersionSelection.new(
|
|
20
20
|
in_range: in_range,
|
|
21
21
|
selected: VersionScopeFilter.new(@version_scope).call(@time_range.scope(relation),
|
|
@@ -37,7 +37,7 @@ module PaperTrailDiff
|
|
|
37
37
|
|
|
38
38
|
#: (untyped) -> untyped
|
|
39
39
|
def trailing_version(relation)
|
|
40
|
-
@time_range.trailing_scope(relation)
|
|
40
|
+
VersionQuery.chronological(@time_range.trailing_scope(relation)).first
|
|
41
41
|
end
|
|
42
42
|
|
|
43
43
|
#: (Array[untyped]) -> Array[untyped]
|
|
@@ -30,10 +30,11 @@ module PaperTrailDiff
|
|
|
30
30
|
end
|
|
31
31
|
|
|
32
32
|
# A record with no versions has no first boundary to resolve, which
|
|
33
|
-
# is an empty history rather than a bad request.
|
|
33
|
+
# is an empty history rather than a bad request. Both endpoints are
|
|
34
|
+
# required, so only `:first` can resolve to nothing; a window has none.
|
|
34
35
|
#: () -> bool
|
|
35
36
|
def unresolved?
|
|
36
|
-
|
|
37
|
+
!time? && (@from.nil? || @to.nil?)
|
|
37
38
|
end
|
|
38
39
|
|
|
39
40
|
# A batch may have selected these versions already, in which case reselecting
|
|
@@ -97,7 +98,7 @@ module PaperTrailDiff
|
|
|
97
98
|
|
|
98
99
|
#: (untyped) -> bool
|
|
99
100
|
def symbolic?(boundary)
|
|
100
|
-
boundary.
|
|
101
|
+
boundary.instance_of?(Symbol)
|
|
101
102
|
end
|
|
102
103
|
|
|
103
104
|
# Resolving `:first` here keeps callers from depending on the
|
|
@@ -118,7 +119,7 @@ module PaperTrailDiff
|
|
|
118
119
|
|
|
119
120
|
#: () -> untyped
|
|
120
121
|
def ordered_versions
|
|
121
|
-
Endpoint.versions(@record)
|
|
122
|
+
VersionQuery.chronological(Endpoint.versions(@record))
|
|
122
123
|
end
|
|
123
124
|
|
|
124
125
|
#: (untyped) -> TimeRange?
|