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.
Files changed (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +648 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +15 -23
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
@@ -64,8 +64,8 @@ module PaperTrailDiff
64
64
  attributes = version.object_deserialized
65
65
  return unless attributes.is_a?(Hash)
66
66
 
67
- attributes = Support.decodable(attributes)
68
- model_class = reification_class(version, attributes)
67
+ model_class = reification_class(version, attributes.transform_keys(&:to_s))
68
+ attributes = Support.decodable(attributes, model_class)
69
69
  return unless direct_attributes?(model_class, attributes)
70
70
 
71
71
  object_attribute_serializer(model_class).deserialize(attributes)
@@ -127,47 +127,25 @@ module PaperTrailDiff
127
127
  @states = {} #: Hash[untyped, PreparedRecordState?]
128
128
  end
129
129
 
130
- #: (untyped) -> untyped
131
- def record_before(boundary)
132
- state_before(boundary)&.instantiate
133
- end
134
-
135
- # A record created in the boundary's own transaction has no state before
136
- # it, yet a HABTM checkpoint saved later in that transaction records it as
137
- # a member. Such a member is read as it was created, at a boundary after
138
- # its creation; before it, the record did not exist yet.
139
- #: (untyped) -> untyped
140
- def record_created_in(boundary)
141
- index = transaction_index(boundary)
142
- return unless index
143
-
144
- version = versions.fetch(index)
145
- return unless version.event == 'create' && !VersionBoundary.at_or_after?(version, boundary)
146
-
147
- state_after(index)&.instantiate
148
- end
149
-
150
- #: (untyped) -> PreparedRecordState?
151
- def state_before(boundary)
152
- index = boundary_index(boundary)
130
+ # `ends` says where each transaction of the timeline being read takes
131
+ # effect. A record then reads as it stood before every transaction that
132
+ # ends at or after the boundary's own (see TransactionEnds); without it,
133
+ # as it stood before the boundary's transaction.
134
+ #: (untyped, ?TransactionEnds?) -> PreparedRecordState?
135
+ def state_before(boundary, ends = nil)
136
+ index = ends ? effective_index(boundary, ends) : boundary_index(boundary)
153
137
  return state_for(versions.fetch(index)) if index
154
138
 
155
139
  live
156
140
  end
157
141
 
158
142
  # A handled nil is known absence, not permission to query the current row.
159
- #: (untyped, ?direct: bool) -> [bool, untyped]
160
- def record_after(version, direct: false)
143
+ #: (untyped) -> [bool, PreparedRecordState?]
144
+ def record_after(version)
161
145
  index = @version_positions[version.id.to_s]
162
146
  return [false, nil] unless index
163
147
 
164
- state = state_after(index)
165
- [true, direct ? state : state&.instantiate]
166
- end
167
-
168
- #: () -> Array[untyped]
169
- def records
170
- states.map(&:instantiate)
148
+ [true, state_after(index)]
171
149
  end
172
150
 
173
151
  #: () -> Array[PreparedRecordState]
@@ -192,6 +170,14 @@ module PaperTrailDiff
192
170
  [state_for(first), state_after(@version_positions.fetch(last.id.to_s))].compact
193
171
  end
194
172
 
173
+ # The states before the transaction of another record's version `first`
174
+ # and after the transaction of its version `last`: what this record was
175
+ # while that record's transaction began and once it had ended.
176
+ #: (untyped, untyped) -> Array[PreparedRecordState]
177
+ def states_around(first, last)
178
+ [state_before(first), state_after_transaction(last)].compact
179
+ end
180
+
195
181
  #: (untyped) -> [PreparedRecordState, PreparedRecordState]?
196
182
  def transition(version)
197
183
  index = @version_positions[version.id.to_s]
@@ -213,6 +199,19 @@ module PaperTrailDiff
213
199
  # @rbs @states: Hash[untyped, PreparedRecordState?]
214
200
  # @rbs @version_positions: Hash[String, Integer]
215
201
  # @rbs @transaction_positions: Hash[untyped, Integer]
202
+ # @rbs @effective: [TransactionEnds, Array[untyped]]?
203
+
204
+ # The state before this record's first version past `boundary` and its
205
+ # transaction, or the live one.
206
+ #: (untyped) -> PreparedRecordState?
207
+ def state_after_transaction(boundary)
208
+ key = VersionBoundary.transaction_id(boundary)
209
+ later = versions.find do |version|
210
+ VersionBoundary.at_or_after?(version, boundary) &&
211
+ (key.nil? || VersionBoundary.transaction_id(version) != key)
212
+ end
213
+ later ? state_for(later) : live
214
+ end
216
215
 
217
216
  #: (Integer) -> PreparedRecordState?
218
217
  def state_after(index)
@@ -231,7 +230,7 @@ module PaperTrailDiff
231
230
 
232
231
  # A version is eligible when it is at or after the boundary, or shares the
233
232
  # boundary's transaction. The first is monotonic over the chronological
234
- # list and the second is indexed, so neither rescans a long history once
233
+ # list and the other is indexed, so neither rescans a long history once
235
234
  # per boundary.
236
235
  #
237
236
  # "At or after" is decided by the version order rather than the timestamp
@@ -246,11 +245,43 @@ module PaperTrailDiff
246
245
  VersionBoundary.at_or_after?(versions.fetch(index), boundary,
247
246
  time: @times.fetch(index), boundary_time: boundary_time)
248
247
  end
249
- transactional = transaction_index(boundary)
250
- return chronological unless transactional
251
- return transactional unless chronological
248
+ [chronological, transaction_index(boundary)].compact.min
249
+ end
250
+
251
+ # The first version whose transaction ends at or after the boundary's.
252
+ # One record's versions end in the order they
253
+ # were saved, since a transaction holds a record it saved until it ends;
254
+ # where history says otherwise, a version counts as ending no earlier
255
+ # than those before it.
256
+ #: (untyped, TransactionEnds) -> Integer?
257
+ def effective_index(boundary, ends)
258
+ target, target_time = ends.target(boundary)
259
+ effective = effective_versions(ends)
260
+ (0...effective.length).bsearch do |index|
261
+ VersionBoundary.at_or_after?(effective.fetch(index), target, boundary_time: target_time)
262
+ end
263
+ end
264
+
265
+ # Where each version takes effect: the last version of its transaction,
266
+ # or of an earlier version's when that one ends later.
267
+ #: (TransactionEnds) -> Array[untyped]
268
+ def effective_versions(ends)
269
+ held = @effective
270
+ return held.last if held && held.first.equal?(ends)
252
271
 
253
- [chronological, transactional].min
272
+ effective = placed(ends)
273
+ @effective = [ends, effective]
274
+ effective
275
+ end
276
+
277
+ #: (TransactionEnds) -> Array[untyped]
278
+ def placed(ends)
279
+ latest = nil
280
+ versions.map do |version|
281
+ last = ends.last(version)
282
+ latest = last if latest.nil? || Support.compare_versions(last, latest).positive?
283
+ latest
284
+ end
254
285
  end
255
286
 
256
287
  #: (untyped) -> Integer?
@@ -297,13 +328,12 @@ module PaperTrailDiff
297
328
  def initialize(start_at, end_at: nil, live_records: [])
298
329
  @start_time = boundary_time(start_at)
299
330
  @end_time = boundary_time(end_at)
300
- @seeded_live_records = live_records.to_h do |record|
301
- [identity(record.class, record.id), record]
302
- end
331
+ @seeded_live_records = live_records.to_h { |row| [identity(row.class, row.id), row] }
303
332
  @state_loader = PreparedVersionStateLoader.new
304
333
  @series = {} #: Hash[Array[String], PreparedRecordSeries]
334
+ @recorded_ends = RecordedTransactionEnds.new
305
335
  @direct_loader = DirectRecordStateLoader.new
306
- @direct_states = {} #: Hash[PreparedRecordState, PreparedRecordState?]
336
+ @direct_states = {} #: Hash[PreparedRecordState, PreparedRecordState]
307
337
  end
308
338
 
309
339
  #: (untyped, Array[untyped]) -> void
@@ -312,48 +342,47 @@ module PaperTrailDiff
312
342
  return if missing.empty?
313
343
 
314
344
  versions = versions_for(model_class, missing).group_by { |version| version.item_id.to_s }
315
- live = available_live_records(model_class, missing).to_h do |record|
316
- [record.id.to_s, record]
317
- end
345
+ live = available_live_records(model_class, missing).to_h { |record| [record.id.to_s, record] }
318
346
  missing.each { |id| add_series(model_class, id, versions, live) }
319
347
  end
320
348
 
321
- #: (untyped, Array[untyped], Array[untyped]) -> void
322
- def seed(model_class, ids, versions)
323
- grouped = versions.group_by { |version| version.item_id.to_s }
324
- live = available_live_records(model_class, ids).to_h { |record| [record.id.to_s, record] }
325
- ids.each { |id| add_series(model_class, id, grouped, live) }
326
- end
327
-
328
- # The transactions the versions held from the start onward belong to that
329
- # began before it, and where the earliest of them began; see
330
- # PreparedHistoryLoader. Nothing when none did.
331
- #: () -> [Array[Array[untyped]], untyped]?
332
- def opening
333
- start = @start_time
334
- start && OpeningTransactions.new(@series, start).call
335
- end
336
-
337
- #: (untyped, untyped, untyped) -> untyped
338
- def record_before(model_class, id, boundary)
339
- @series.fetch(identity(model_class, id)).record_before(boundary)
340
- end
341
-
342
- #: (untyped, untyped, untyped) -> untyped
343
- def record_created_in(model_class, id, boundary)
344
- @series.fetch(identity(model_class, id)).record_created_in(boundary)
345
- end
349
+ # When the history was read from.
350
+ #: () -> untyped
351
+ attr_reader :start_time
346
352
 
347
- #: (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
353
+ # When it was read to, if it ends.
354
+ #: () -> untyped
355
+ attr_reader :end_time
356
+
357
+ # Where the transactions of these versions take effect, as their version
358
+ # tables record it (see RecordedTransactionEnds).
359
+ #: (Array[untyped]) -> TransactionEnds
360
+ def transaction_ends(versions)
361
+ TransactionEnds.new(versions, @recorded_ends.call(versions) { self.versions })
362
+ end
363
+
364
+ # Reads for a root's timeline, each record as it stood before every
365
+ # transaction that had not ended at the boundary it is read at (see
366
+ # TransactionEnds).
367
+ #: (TransactionEnds) { () -> void } -> void
368
+ def reading(ends)
369
+ previous = @ends
370
+ @ends = ends
371
+ yield
372
+ ensure
373
+ @ends = previous
374
+ end
375
+
376
+ # What a read is made with now, if a timeline is being read.
377
+ #: () -> TransactionEnds?
378
+ def reading_ends = @ends
379
+
380
+ # The record's state at the boundary, as a record of its class would
381
+ # hold it. The record must be loaded.
382
+ #: (untyped, untyped, untyped) -> PreparedRecordState?
348
383
  def snapshot_state_before(model_class, id, boundary)
349
- series = @series[identity(model_class, id)]
350
- return [false, nil] unless series
351
-
352
- state = series.state_before(boundary)
353
- return [true, nil] unless state
354
-
355
- prepared = direct_state(state)
356
- [!prepared.nil?, prepared]
384
+ state = @series.fetch(identity(model_class, id)).state_before(boundary, @ends)
385
+ direct_state(state) if state
357
386
  end
358
387
 
359
388
  # Typed as a reified record's attributes are. A JSON or JSONB `object`
@@ -367,19 +396,14 @@ module PaperTrailDiff
367
396
  [typed_attributes(states.fetch(0)), typed_attributes(states.fetch(1))]
368
397
  end
369
398
 
370
- #: (untyped, untyped, untyped, ?direct: bool) -> [bool, untyped]
371
- def record_after(model_class, id, version, direct: false)
372
- handled, state = @series[identity(model_class, id)]&.record_after(version, direct: direct)
399
+ # The record as the version left it, completed as snapshot_state_before's
400
+ # state is. A handled nil is known absence: the version destroyed it.
401
+ #: (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
402
+ def record_after(model_class, id, version)
403
+ handled, state = @series[identity(model_class, id)]&.record_after(version)
373
404
  return [false, nil] unless handled
374
- return [true, state] unless direct && state
375
405
 
376
- prepared = direct_state(state)
377
- [!prepared.nil?, prepared]
378
- end
379
-
380
- #: (untyped, Array[untyped]) -> Array[untyped]
381
- def records_for(model_class, ids)
382
- ids.flat_map { |id| @series.fetch(identity(model_class, id)).records }
406
+ [true, state && direct_state(state)]
383
407
  end
384
408
 
385
409
  #: (untyped, Array[untyped], String) -> Array[untyped]
@@ -387,8 +411,7 @@ module PaperTrailDiff
387
411
  plain_reader = generated_reader?(model_class, name)
388
412
  ids.flat_map do |id|
389
413
  @series.fetch(identity(model_class, id)).states.map do |state|
390
- direct = direct_state(state) if plain_reader
391
- direct ? direct.attributes[name] : state.instantiate.public_send(name)
414
+ plain_reader ? direct_state(state).attributes[name] : state.instantiate.public_send(name)
392
415
  end
393
416
  end
394
417
  end
@@ -416,6 +439,14 @@ module PaperTrailDiff
416
439
  .map { |state| typed_attributes(state) }
417
440
  end
418
441
 
442
+ # A record's attributes around another record's transaction (see
443
+ # PreparedRecordSeries#states_around), typed as typed_states_across's.
444
+ #: (untyped, untyped, untyped, untyped) -> Array[Hash[untyped, untyped]]
445
+ def typed_states_around(model_class, id, first, last)
446
+ @series.fetch(identity(model_class, id)).states_around(first, last)
447
+ .map { |state| typed_attributes(state) }
448
+ end
449
+
419
450
  #: (untyped, untyped) -> bool
420
451
  def loaded?(model_class, id)
421
452
  @series.key?(identity(model_class, id))
@@ -423,21 +454,18 @@ module PaperTrailDiff
423
454
 
424
455
  private
425
456
 
426
- # A model whose records need their own initialization is cast by
427
- # instantiating it, as reify does.
428
457
  #: (PreparedRecordState) -> Hash[untyped, untyped]
429
- def typed_attributes(state)
430
- typed = direct_state(state)
431
- return typed.attributes if typed
432
-
433
- PreparedRecordState.new(state.instantiate).attributes
434
- end
458
+ def typed_attributes(state) = direct_state(state).attributes
435
459
 
436
- # A state completed as a record of its class would hold it, or nil where
437
- # only instantiating can tell; each state is completed once.
438
- #: (PreparedRecordState) -> PreparedRecordState?
460
+ # A state completed as a record of its class would hold it; each state is
461
+ # completed once. A model whose records need their own initialization is
462
+ # completed by instantiating it, as reify does.
463
+ #: (PreparedRecordState) -> PreparedRecordState
439
464
  def direct_state(state)
440
- @direct_states.fetch(state) { @direct_states[state] = @direct_loader.complete(state) }
465
+ @direct_states.fetch(state) do
466
+ @direct_states[state] = @direct_loader.complete(state) ||
467
+ PreparedRecordState.new(state.instantiate)
468
+ end
441
469
  end
442
470
 
443
471
  #: (untyped, String) -> bool
@@ -452,7 +480,9 @@ module PaperTrailDiff
452
480
  # @rbs @state_loader: PreparedVersionStateLoader
453
481
  # @rbs @series: Hash[Array[String], PreparedRecordSeries]
454
482
  # @rbs @direct_loader: DirectRecordStateLoader
455
- # @rbs @direct_states: Hash[PreparedRecordState, PreparedRecordState?]
483
+ # @rbs @direct_states: Hash[PreparedRecordState, PreparedRecordState]
484
+ # @rbs @ends: TransactionEnds?
485
+ # @rbs @recorded_ends: RecordedTransactionEnds
456
486
 
457
487
  # Callers bound the range with either a version or a bare timestamp.
458
488
  #: (untyped) -> untyped
@@ -524,58 +554,102 @@ module PaperTrailDiff
524
554
  end
525
555
  end
526
556
 
527
- # Finds the transactions that crossed a history's start: those the versions
528
- # held from the start onward belong to that also saved versions before it,
529
- # of any record. One statement per 500 transactions.
530
- class OpeningTransactions
531
- #: (Hash[Array[String], PreparedRecordSeries], untyped) -> void
532
- def initialize(series, start)
533
- @series = series
557
+ # Finds where the earliest transaction open at a window's start began.
558
+ #
559
+ # A transaction open at the start saved a version before it and another
560
+ # from it onward. Either can be of a record the history does not hold, such
561
+ # as one the transaction moved out of the tree before the window and never
562
+ # saved again, so every such transaction of the tree's version tables is
563
+ # read, not only those of the versions held: one statement per table.
564
+ #
565
+ # Another version table can number a transaction as this one numbered an
566
+ # earlier one, so versions an anchor separates from the start are not read
567
+ # as one transaction's (see TransactionAnchors).
568
+ #
569
+ # Nothing is read past a window's end. A transaction that crosses it is
570
+ # placed by its last version, which its version table names (see
571
+ # RecordedTransactionEnds), so after the window.
572
+ class CrossingTransactions
573
+ #: (Enumerable[untyped], untyped) -> void
574
+ def initialize(version_classes, start)
575
+ @version_classes = version_classes
534
576
  @start = start
535
577
  end
536
578
 
537
- # Their keys, as ActivityTransactionGroups keys a version's, and when the
538
- # earliest began; nil when none crossed the start.
539
- #: () -> [Array[Array[untyped]], untyped]?
540
- def call
541
- began = transactions.flat_map do |version_class, ids|
542
- earliest(version_class, ids).map { |id, at| [[version_class.name, id], at] }
543
- end
544
- return if began.empty?
579
+ # Where the transactions open at `start` began, in these version tables;
580
+ # nil when none is open, or without a start.
581
+ #: (Enumerable[untyped], untyped) -> untyped
582
+ def self.reach(version_classes, start)
583
+ new(version_classes, start).call if start
584
+ end
545
585
 
546
- [began.map(&:first), began.map(&:last).min]
586
+ # The same, in the version tables of the models of these names that
587
+ # PaperTrail tracks.
588
+ #: (Array[String], untyped) -> untyped
589
+ def self.open_among(types, start)
590
+ models = types.map { |type| Support.constant(type) }
591
+ .select { |model| Support.versioned?(model) }
592
+ reach(models.map { |model| model.paper_trail.version_class }.uniq, start)
547
593
  end
548
594
 
549
- private
595
+ # The same, in the version tables of a root model and of the records on
596
+ # its requested paths. A polymorphic belongs_to may reach a record of any
597
+ # class, so with one every version table is read.
598
+ #: (untyped, AssociationTraversal, untyped) -> untyped
599
+ def self.open_around(model, traversal, start)
600
+ return reach(every_version_class, start) if traversal.polymorphic_paths?(model)
550
601
 
551
- # When each of these transactions saved its first version before the
552
- # start, for those that saved one there.
553
- #: (untyped, Array[untyped]) -> Array[[untyped, untyped]]
554
- def earliest(version_class, transaction_ids)
555
- before = version_class.arel_table[:created_at].lt(@start)
556
- transaction_ids.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
557
- version_class.where(transaction_id: slice).where(before).group(:transaction_id)
558
- .minimum(:created_at).to_a
559
- end
602
+ open_among([model.name, *traversal.path_types(model)], start)
560
603
  end
561
604
 
562
- # @rbs @series: Hash[Array[String], PreparedRecordSeries]
605
+ # One version class for each version table the application defines. An
606
+ # abstract class has no table of its own.
607
+ #: () -> Array[untyped]
608
+ def self.every_version_class
609
+ concern = Support.constant('PaperTrail::VersionConcern')
610
+ Support.constant('ActiveRecord::Base').descendants.select do |candidate|
611
+ candidate.include?(concern) && candidate.table_exists?
612
+ end.uniq(&:table_name)
613
+ end
614
+ private_class_method :every_version_class
615
+
616
+ # The versions of this table saved before `start` by the transactions
617
+ # open at it.
618
+ #: (untyped, untyped) -> untyped
619
+ def self.saved_before(version_class, start)
620
+ saved = version_class.where(version_class.arel_table[:created_at].lt(start))
621
+ TransactionAnchors.scope(saved, version_class, start)
622
+ .where(transaction_id: later(version_class, start).select(:transaction_id))
623
+ end
624
+
625
+ # The versions saved from the start onward, of the transactions no anchor
626
+ # separates from it. A transaction's versions can be dated out of the
627
+ # order they were saved in, as when a callback saves other records before
628
+ # its own version, dated as its save began, so each is judged by its date.
629
+ #: (untyped, untyped) -> untyped
630
+ def self.later(version_class, start)
631
+ table = version_class.arel_table
632
+ saved = version_class.where(table[:created_at].gteq(start)).where.not(transaction_id: nil)
633
+ TransactionAnchors.scope(saved, version_class, start)
634
+ end
635
+ private_class_method :later
636
+
637
+ #: () -> untyped
638
+ def call
639
+ @version_classes.filter_map { |version_class| open_at_start(version_class) }.min
640
+ end
641
+
642
+ private
643
+
644
+ # @rbs @version_classes: Enumerable[untyped]
563
645
  # @rbs @start: untyped
564
646
 
565
- # The transactions of the versions held from the start onward, by version
566
- # class, since each version table numbers its own.
567
- #: () -> Hash[untyped, Array[untyped]]
568
- def transactions
569
- found = {} #: Hash[untyped, Array[untyped]]
570
- @series.each_value do |series|
571
- series.versions.each do |version|
572
- transaction_id = VersionBoundary.transaction_id(version)
573
- next unless transaction_id && version.created_at >= @start
574
-
575
- (found[version.class] ||= []) << transaction_id
576
- end
577
- end
578
- found.transform_values(&:uniq)
647
+ # When the earliest transaction open at the start began in this table.
648
+ #: (untyped) -> untyped
649
+ def open_at_start(version_class)
650
+ return unless version_class.column_names.include?('transaction_id')
651
+
652
+ self.class.saved_before(version_class, @start).minimum(:created_at)
579
653
  end
580
654
  end
581
655
  end
@@ -2,79 +2,84 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Normalizes supported recorded graphs without historical ActiveRecord instances.
5
+ # Normalizes recorded graphs from prepared history, reading each member's
6
+ # state without rebuilding its record.
6
7
  class PreparedSnapshotBuilder
7
8
  #: (AssociationTraversal) -> void
8
9
  def initialize(traversal)
9
10
  @traversal = traversal
10
11
  @loader = DirectRecordStateLoader.new
12
+ @reified = {} #: Hash[Array[untyped], PreparedRecordState?]
11
13
  end
12
14
 
13
- #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [bool, RecordSnapshot?]
15
+ #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
14
16
  def call(version, boundary, tree:, normalizer:, history:)
15
- return [true, nil] unless version.object
16
-
17
- state = @loader.call(version)
18
- return [false, nil] unless state
19
-
20
- build(state, boundary, tree, normalizer, history, path: '')
17
+ state = state(version)
18
+ build(state, boundary, tree, normalizer, history, path: '') if state
21
19
  end
22
20
 
23
21
  # The state `call` builds a version's snapshot from, or nil when the
24
- # version stored none or must be reified.
22
+ # version stored none. A model whose records need their own
23
+ # initialization is read by reifying it, once per version.
25
24
  #: (untyped) -> PreparedRecordState?
26
25
  def state(version)
27
- @loader.call(version) if version.object
26
+ return unless version.object
27
+
28
+ @loader.call(version) || @reified.fetch(Support.row_key(version)) do |key|
29
+ @reified[key] = reified_state(version)
30
+ end
28
31
  end
29
32
 
30
33
  # The current row of a root, given as its state, with its associations as
31
- # `boundary` reads them. Its attributes are the record's own, as the record
32
- # path normalizes them, so its model need not be plain; its members are
33
- # read as a version's are.
34
- #: (PreparedRecordState, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [bool, RecordSnapshot?]
34
+ # `boundary` reads them. Its attributes are the record's own, as the
35
+ # current snapshot normalizes them, so its model need not be plain; its
36
+ # members are read as a version's are.
37
+ #: (PreparedRecordState, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot
35
38
  def live(state, boundary, tree:, normalizer:, history:)
36
39
  build(state, boundary, tree, normalizer, history, path: '')
37
40
  end
38
41
 
39
- private
40
-
41
- # @rbs @traversal: AssociationTraversal
42
- # @rbs @loader: DirectRecordStateLoader
43
-
44
- #: (PreparedRecordState, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory?, path: String, ?incoming: untyped) -> [bool, RecordSnapshot?]
42
+ # A state at `path` of the tree, with the associations `tree` selects
43
+ # below it as `boundary` reads them.
44
+ #: (PreparedRecordState, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory?, path: String, ?incoming: untyped) -> RecordSnapshot
45
45
  def build(state, boundary, tree, normalizer, history, path:, incoming: nil) # rubocop:disable Metrics/ParameterLists
46
46
  associations = {} #: snapshot_associations
47
47
  @traversal.reflections_for(state.model_class, tree, path: path).each do |reflection|
48
- return [false, nil] unless history
48
+ unless history
49
+ raise UnsupportedAssociationError,
50
+ "association #{state.model_class.name}##{reflection.name} cannot be read: " \
51
+ 'no history was prepared for it'
52
+ end
49
53
 
50
- handled, snapshot = association(state, reflection, boundary, tree, normalizer, history,
51
- path)
52
- return [false, nil] unless handled && snapshot
53
-
54
- associations[reflection.name.to_s] = snapshot
54
+ associations[reflection.name.to_s] =
55
+ association(state, reflection, boundary, tree, normalizer, history, path)
55
56
  end
56
- [true, normalizer.from_state(state, tree: tree, path: path,
57
- incoming: incoming, associations: associations)]
57
+ normalizer.from_state(state, tree: tree, path: path, incoming: incoming,
58
+ associations: associations)
58
59
  end
59
60
 
60
- #: (PreparedRecordState, untyped, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory, String) -> [bool, AssociationSnapshot?]
61
- def association(owner, reflection, boundary, tree, normalizer, history, path) # rubocop:disable Metrics/ParameterLists
62
- handled, states = history.snapshot_states(owner, reflection, boundary)
63
- return [false, nil] unless handled
61
+ private
62
+
63
+ # @rbs @traversal: AssociationTraversal
64
+ # @rbs @loader: DirectRecordStateLoader
65
+ # @rbs @reified: Hash[Array[untyped], PreparedRecordState?]
64
66
 
65
- subtree = tree.child(reflection.name)
66
- return [false, nil] unless subtree
67
+ #: (untyped) -> PreparedRecordState?
68
+ def reified_state(version)
69
+ record = Support.reify(version, dup: true, has_many: false, has_one: false,
70
+ belongs_to: false, has_and_belongs_to_many: false)
71
+ PreparedRecordState.new(record) if record
72
+ end
67
73
 
74
+ #: (PreparedRecordState, untyped, untyped, AssociationTree, SnapshotNormalizer, PreparedHistory, String) -> AssociationSnapshot
75
+ def association(owner, reflection, boundary, tree, normalizer, history, path) # rubocop:disable Metrics/ParameterLists
76
+ subtree = tree.child(reflection.name) #: AssociationTree
68
77
  child_path = Support.association_path(path, reflection.name)
69
- records = [] #: Array[RecordSnapshot]
70
- states.each do |state|
71
- supported, snapshot = build(state, boundary, subtree, normalizer, history,
72
- path: child_path, incoming: reflection)
73
- return [false, nil] unless supported && snapshot
74
-
75
- records << snapshot
78
+ records = history.snapshot_states(owner, reflection, boundary).map do |state|
79
+ build(state, boundary, subtree, normalizer, history, path: child_path,
80
+ incoming: reflection)
76
81
  end
77
- [true, AssociationSnapshot.new(kind: reflection.macro, records: records)]
82
+ AssociationSnapshot.new(kind: reflection.macro, records: records)
78
83
  end
79
84
  end
80
85
  end