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
@@ -53,9 +53,8 @@ module PaperTrailDiff
53
53
 
54
54
  #: (untyped) -> Array[untyped]
55
55
  def relationship_keys(reflection)
56
- keys = Array(reflection.foreign_key)
57
- keys << reflection.type if reflection.options.key?(:as)
58
- keys
56
+ key = reflection.foreign_key
57
+ reflection.options.key?(:as) ? [key, reflection.type] : [key]
59
58
  end
60
59
  end
61
60
  end
@@ -21,7 +21,7 @@ module PaperTrailDiff
21
21
  #
22
22
  # A `start_at` is a window's; a range of versions starts at its first.
23
23
  #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
24
- def prepare(record, root_versions, start_at: nil, end_at: root_versions.last.created_at)
24
+ def prepare(record, root_versions, start_at: nil, end_at: nil)
25
25
  history = @store.prepare(record, root_versions, start_at: start_at, end_at: end_at)
26
26
  last = @last
27
27
  return last if last && last.history.equal?(history)
@@ -35,6 +35,14 @@ module PaperTrailDiff
35
35
  @snapshotter.call(root_endpoint, context_endpoint)
36
36
  end
37
37
 
38
+ # See HistoricalSnapshotStore#range_end_of.
39
+ #: (untyped, untyped) -> untyped
40
+ def range_end(record, version) = @store.range_end_of(record, version)
41
+
42
+ # See HistoricalSnapshotStore#reach_before.
43
+ #: (untyped, untyped) -> untyped
44
+ def reach_before(record, start_at) = @store.reach_before(record, start_at)
45
+
38
46
  # @rbs @store: HistoricalSnapshotStore
39
47
  # @rbs @snapshotter: untyped
40
48
  # @rbs @refresher: untyped
@@ -60,9 +68,12 @@ module PaperTrailDiff
60
68
  @history&.activity_index
61
69
  end
62
70
 
63
- #: () -> Array[Array[untyped]]
64
- def opening_transactions
65
- @history&.opening_transactions || []
71
+ # Reads with where each transaction of a root's timeline takes effect
72
+ # (see TransactionEnds).
73
+ #: (TransactionEnds) { () -> void } -> void
74
+ def reading(ends, &block)
75
+ history = @history
76
+ history ? history.reading(ends, &block) : yield
66
77
  end
67
78
 
68
79
  #: (untyped, untyped) -> RecordSnapshot?
@@ -81,6 +92,12 @@ module PaperTrailDiff
81
92
  @refresher.advance_root(root_endpoint, context_endpoint, previous_snapshot, event: event)
82
93
  end
83
94
 
95
+ #: (untyped, untyped, RecordSnapshot, Array[String]?, Array[ActivityEvent]) -> RecordSnapshot?
96
+ def apply_transaction(root_endpoint, context_endpoint, previous_snapshot, branches, events)
97
+ @refresher.apply_transaction(root_endpoint, context_endpoint, previous_snapshot, branches,
98
+ events)
99
+ end
100
+
84
101
  # The branches a refresh rebuilds, with this root's history.
85
102
  #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
86
103
  def custom(root_endpoint, context_endpoint, tree:, normalizer:)
@@ -95,9 +112,11 @@ module PaperTrailDiff
95
112
  @store.root_state(root_endpoint) if @history
96
113
  end
97
114
 
98
- #: (untyped, habtm_version: untyped) -> untyped
99
- def association_reader(context_version, habtm_version:)
100
- @store.association_reader(context_version, habtm_version: habtm_version, history: @history)
115
+ # See HistoricalSnapshotStore#member.
116
+ #: (PreparedRecordState, untyped, tree: AssociationTree, path: String, incoming: untyped, normalizer: SnapshotNormalizer) -> RecordSnapshot
117
+ def member(state, context_version, tree:, path:, incoming:, normalizer:) # rubocop:disable Metrics/ParameterLists
118
+ @store.member(state, context_version, tree: tree, path: path, incoming: incoming,
119
+ normalizer: normalizer, history: @history)
101
120
  end
102
121
 
103
122
  #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
@@ -105,10 +124,10 @@ module PaperTrailDiff
105
124
  @history&.record_transition(Endpoint.model_class(version), version.item_id, version)
106
125
  end
107
126
 
108
- #: (untyped, ?direct: bool) -> [bool, untyped]
109
- def record_after(version, direct: false)
110
- @history&.record_after(Endpoint.model_class(version), version.item_id, version,
111
- direct: direct) || [false, nil]
127
+ #: (untyped) -> [bool, PreparedRecordState?]
128
+ def record_after(version)
129
+ @history&.record_after(Endpoint.model_class(version), version.item_id, version) ||
130
+ [false, nil]
112
131
  end
113
132
 
114
133
  # @rbs @store: HistoricalSnapshotStore
@@ -118,23 +137,30 @@ module PaperTrailDiff
118
137
 
119
138
  # Builds chronological snapshots, refreshing only branches affected by prior events.
120
139
  class ActivitySnapshotSequence
121
- #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped) -> void
122
- def initialize(root_versions, events, snapshotter, current: nil)
140
+ # `ends` places the events' transactions, as the events were ordered by.
141
+ #: (Array[untyped], Array[ActivityEvent], untyped, ends: TransactionEnds, ?current: untyped) -> void
142
+ def initialize(root_versions, events, snapshotter, ends:, current: nil)
123
143
  @root_versions = root_versions
124
144
  @events = events
125
145
  @snapshotter = snapshotter
126
146
  @current = current
127
- @transaction_groups = ActivityTransactionGroups.new(
128
- events, opening: snapshotter.opening_transactions
129
- )
147
+ @ends = ends
148
+ @transaction_groups = ActivityTransactionGroups.new(events)
130
149
  @root_endpoints = build_root_endpoints
131
150
  end
132
151
 
133
152
  #: () { (ActivityEvent, RecordSnapshot?) -> void } -> void
134
- def each
153
+ def each(&block)
135
154
  first = @events.first
136
155
  return unless first
137
156
 
157
+ @snapshotter.reading(@ends) { replay(first, &block) }
158
+ end
159
+
160
+ private
161
+
162
+ #: (ActivityEvent) { (ActivityEvent, RecordSnapshot?) -> void } -> void
163
+ def replay(first)
138
164
  previous_snapshot = full_snapshot(first)
139
165
  yield first, previous_snapshot
140
166
  @events.each_cons(2) do |pair|
@@ -145,12 +171,11 @@ module PaperTrailDiff
145
171
  end
146
172
  end
147
173
 
148
- private
149
-
150
174
  # @rbs @root_versions: Array[untyped]
151
175
  # @rbs @events: Array[ActivityEvent]
152
176
  # @rbs @snapshotter: untyped
153
177
  # @rbs @current: untyped
178
+ # @rbs @ends: TransactionEnds
154
179
  # @rbs @transaction_groups: ActivityTransactionGroups
155
180
  # @rbs @root_endpoints: Hash[untyped, untyped]
156
181
 
@@ -161,6 +186,8 @@ module PaperTrailDiff
161
186
 
162
187
  branches = @transaction_groups.branches_for(previous_event)
163
188
  return rebuilt_snapshot(previous_event, event, previous_snapshot) unless branches
189
+ return transaction_snapshot(previous_event, event, previous_snapshot, branches) if
190
+ previous_snapshot && !@transaction_groups.isolated?(previous_event)
164
191
 
165
192
  @snapshotter.refresh(
166
193
  root_endpoint(event.version),
@@ -172,24 +199,63 @@ module PaperTrailDiff
172
199
  )
173
200
  end
174
201
 
202
+ # A transaction that saved several records is read whole once it ends:
203
+ # until then the records it saved read as they stood before it began, so
204
+ # the snapshot is the same from one of its events to the next. At the
205
+ # event after its last, each of its versions is applied to the record it
206
+ # saved, rather than reading their branches again, which costs every
207
+ # record in them. `branches` are those of a transaction without a root
208
+ # event, and nil for one with.
209
+ #: (ActivityEvent, ActivityEvent, RecordSnapshot, Array[String]?) -> RecordSnapshot?
210
+ def transaction_snapshot(previous_event, event, previous_snapshot, branches)
211
+ return previous_snapshot if branches && @transaction_groups.shared?(previous_event, event)
212
+
213
+ @snapshotter.apply_transaction(
214
+ root_endpoint(event.version), event.version, previous_snapshot, branches,
215
+ @transaction_groups.events_for(previous_event)
216
+ )
217
+ end
218
+
175
219
  # A transaction with a root event is read whole once it ends. Until then,
176
220
  # PT-AT reads the records it saved as they stood before it began, so from
177
221
  # one descendant's event to the next in the same transaction the snapshot
178
222
  # is the same, and from the root's event to a descendant's only the root's
179
223
  # own version applies, as when it is alone in its transaction. A create
180
224
  # leaves nothing to advance. The root's version can record what the
181
- # transaction changed, such as HABTM membership, so a snapshot at a root
182
- # event is rebuilt.
225
+ # transaction changed, such as HABTM membership, so at a root event those
226
+ # branches are read again. At the event after the transaction's last,
227
+ # each of its versions is applied to the record it saved.
183
228
  #: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
184
229
  def rebuilt_snapshot(previous_event, event, previous_snapshot)
185
- return full_snapshot(event) if event.root?
186
- return full_snapshot(event) unless @transaction_groups.shared?(previous_event, event)
187
- return previous_snapshot unless previous_event.root?
188
230
  return full_snapshot(event) unless previous_snapshot
231
+ return transaction_snapshot(previous_event, event, previous_snapshot, nil) unless
232
+ @transaction_groups.shared?(previous_event, event)
233
+ return within_transaction(previous_event, event, previous_snapshot) if previous_event.root?
234
+
235
+ event.root? ? carried_snapshot(event, previous_snapshot) : previous_snapshot
236
+ end
237
+
238
+ # From the root's event to the next in its transaction: a second version
239
+ # of the root is read again, and a descendant's event takes only the
240
+ # root's own version.
241
+ #: (ActivityEvent, ActivityEvent, RecordSnapshot) -> RecordSnapshot?
242
+ def within_transaction(previous_event, event, previous_snapshot)
243
+ return full_snapshot(event) if event.root?
189
244
 
190
245
  advance_root(previous_event, event, previous_snapshot)
191
246
  end
192
247
 
248
+ # The snapshot at a root's event, from the one at a descendant's event
249
+ # before it in its transaction: the same, but for the branches the
250
+ # root's version itself records.
251
+ #: (ActivityEvent, RecordSnapshot) -> RecordSnapshot?
252
+ def carried_snapshot(event, previous_snapshot)
253
+ branches = [] #: Array[String]
254
+ events = [] #: Array[ActivityEvent]
255
+ @snapshotter.apply_transaction(root_endpoint(event.version), event.version,
256
+ previous_snapshot, branches, events)
257
+ end
258
+
193
259
  #: (ActivityEvent) -> bool
194
260
  def incremental_root?(event)
195
261
  event.root? && @transaction_groups.isolated?(event)
@@ -221,8 +287,9 @@ module PaperTrailDiff
221
287
  endpoints = {} #: Hash[untyped, untyped]
222
288
  endpoints.compare_by_identity
223
289
  @events.each do |event|
290
+ placed = @ends.sort_key(event.version)
224
291
  while @root_versions[root_index] &&
225
- Support.compare_versions(@root_versions[root_index], event.version).negative?
292
+ (@ends.sort_key(@root_versions[root_index]) <=> placed) == -1
226
293
  root_index += 1
227
294
  end
228
295
  endpoint = @root_versions[root_index] || @current || @root_versions.last
@@ -26,17 +26,7 @@ module PaperTrailDiff
26
26
  @filter = (view.version_filter unless @tree.empty?)
27
27
  end
28
28
 
29
- #: () -> Array[ActivityStep]
30
- def build
31
- return steps_of(window_replay) if @range.time?
32
- return no_steps if @range.unresolved?
33
- return steps_of(current_replay) if Endpoint.record?(@to)
34
-
35
- Endpoint.validate!(@to)
36
- steps_of(version_replay)
37
- end
38
-
39
- # The window the range covers once its edges have moved to transactions.
29
+ # The window the range covers, as it was asked for.
40
30
  #: () -> TimeRange?
41
31
  def window
42
32
  @range.time_range
@@ -63,12 +53,8 @@ module PaperTrailDiff
63
53
  # @rbs @snapshotter: untyped
64
54
  # @rbs @view: ActivityView
65
55
  # @rbs @filter: ActivityScopeFilter?
66
-
67
- #: () -> Array[ActivityStep]
68
- def no_steps
69
- steps = [] #: Array[ActivityStep]
70
- steps.freeze
71
- end
56
+ # @rbs @ends: TransactionEnds?
57
+ # @rbs @opening: Array[untyped]?
72
58
 
73
59
  # Each kind of range replays into the same things, or into nil when it
74
60
  # reports no step: its plan and history, the steps it reports, ending with
@@ -81,11 +67,6 @@ module PaperTrailDiff
81
67
  [plan, history, steps, final, snapshot, captured_at] unless steps.empty?
82
68
  end
83
69
 
84
- #: ([RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?) -> Array[ActivityStep]
85
- def steps_of(replay)
86
- replay ? present(replay.fetch(2)) : no_steps
87
- end
88
-
89
70
  # A range that reports no step is empty, whatever its replay read: a
90
71
  # version filter may keep nothing in it, or only the version that ends it,
91
72
  # which opens no step, and a range may run from a version to itself.
@@ -98,7 +79,7 @@ module PaperTrailDiff
98
79
  diff: Engine.compare(history.first_snapshot, final),
99
80
  timeline: ActivityRootSteps.call(plan, history.root_snapshots, closing_snapshot: snapshot,
100
81
  captured_at: captured_at),
101
- activity_timeline: present(steps),
82
+ activity_timeline: @view.present(steps),
102
83
  from_snapshot: history.first_snapshot,
103
84
  to_snapshot: final
104
85
  )
@@ -115,7 +96,19 @@ module PaperTrailDiff
115
96
  def version_replay
116
97
  plan = select_plan
117
98
  history = history_until(plan)
118
- replayed(plan, history, closing_step(history, plan), history.last_snapshot)
99
+ closing = closing_step(history, plan)
100
+ last = history.last_event #: ActivityEvent
101
+ closing = nil if closing && restored?(last)
102
+ replayed(plan, history, closing, history.last_snapshot)
103
+ end
104
+
105
+ # Whether the root, whose destroy a range closes on, was restored after
106
+ # it, saved again under its id. The range from that destroy then reports
107
+ # the removal, in its step to the restoring version, so a range meeting
108
+ # it there leaves the removal to it.
109
+ #: (ActivityEvent) -> bool
110
+ def restored?(destroy)
111
+ VersionQuery.after(@record.class, destroy.version).exists?
119
112
  end
120
113
 
121
114
  # Activity replays every root version in the range, even those a version
@@ -126,18 +119,33 @@ module PaperTrailDiff
126
119
  def select_plan = @range.select_plan(context_required: !@tree.empty?, whole: true)
127
120
 
128
121
  # Whether the event's step is reported: it is inside the range, and a
129
- # version filter keeps it. With associations the filter keeps whole
130
- # transactions (see ActivityScopeFilter). On the root alone it keeps the
131
- # root's versions, as `timeline` does, and so does a plan without one, but
132
- # for the version it holds only to reveal the last change in it.
122
+ # version filter keeps it. A window holds an event when it holds the last
123
+ # version of the event's transaction (see TransactionEnds); an explicit
124
+ # range holds every event it collected. With
125
+ # associations the filter keeps whole transactions (see
126
+ # ActivityScopeFilter). On the root alone it keeps the root's versions, as
127
+ # `timeline` does, and so does a plan without one, but for the version it
128
+ # holds only to reveal the last change in it.
133
129
  #: (ActivityEvent, RootVersionPlan) -> bool
134
130
  def reported?(event, plan)
135
- return false unless @range.include?(event.version)
131
+ ends = @ends #: TransactionEnds
132
+ return false unless in_range?(ends.last(event.version))
136
133
 
137
134
  filter = @filter
138
135
  filter ? filter.kept?(event.version) : !event.root? || plan.mutation?(event.version)
139
136
  end
140
137
 
138
+ # A window holds the transactions that end inside it; an explicit range
139
+ # those that end where its first version's does, or later.
140
+ #: (untyped) -> bool
141
+ def in_range?(last)
142
+ opening = @opening
143
+ return @range.include?(last) unless opening
144
+
145
+ comparison = (Support.chronological_version_key(last) <=> opening) #: Integer
146
+ comparison >= 0
147
+ end
148
+
141
149
  # The explicit live endpoint and a batch's live closing endpoint use the
142
150
  # same selected plan, which replays every version through to the current
143
151
  # record, a version filter or not.
@@ -163,16 +171,41 @@ module PaperTrailDiff
163
171
  #: (RootVersionPlan, ?RecordSnapshot?, ?untyped) -> ActivityHistory
164
172
  def history_until(plan, snapshot = nil, captured_at = nil)
165
173
  events, snapshots = range_events(plan, captured_at)
166
- replay(plan, events, snapshots, current: plan.closing_record, closing: snapshot)
174
+ events = by_transaction_end(events, plan, closes: captured_at.nil?)
175
+ replay(plan, plan, events, snapshots, current: plan.closing_record, closing: snapshot)
176
+ end
177
+
178
+ # The range starts before its first version's transaction took effect:
179
+ # what another transaction saved before it is part of the starting state
180
+ # if that transaction ended first, and is reported if it ended later. A
181
+ # range that ends at a version ends before that version's transaction
182
+ # took effect, so what took effect after it is left out.
183
+ #: (Array[ActivityEvent], RootVersionPlan, closes: bool) -> Array[ActivityEvent]
184
+ def by_transaction_end(events, plan, closes:)
185
+ ends = @ends #: TransactionEnds
186
+ first = plan.reconstruction_versions.first
187
+ @opening = Support.chronological_version_key(ends.last(first))
188
+ return events unless closes
189
+
190
+ closing = ends.sort_key(plan.reconstruction_versions.last)
191
+ events.select do |event|
192
+ comparison = (ends.sort_key(event.version) <=> closing) #: Integer
193
+ comparison <= 0
194
+ end
167
195
  end
168
196
 
169
197
  # The range's events up to its last root version, or to the instant the
170
198
  # live record it closes on was read, with the history they are read from.
171
- #: (RootVersionPlan, untyped) -> [Array[ActivityEvent], untyped]
172
- def range_events(plan, captured_at)
199
+ # A window is read from where the earliest transaction open at its start
200
+ # began; a range of versions names no start.
201
+ #: (RootVersionPlan, untyped, ?start_at: untyped) -> [Array[ActivityEvent], untyped]
202
+ def range_events(plan, captured_at, start_at: nil)
173
203
  versions = plan.reconstruction_versions
174
- snapshots = prepare_history(versions, end_at: captured_at)
175
- [collect_events(versions, snapshots, range_end: captured_at || versions.last), snapshots]
204
+ range_end = captured_at || @snapshotter.range_end(@record, versions.last)
205
+ end_at = captured_at || range_end.created_at
206
+ snapshots = @snapshotter.prepare(@record, versions, start_at: start_at, end_at: end_at)
207
+ closing = versions.last unless captured_at
208
+ [collect_events(versions, snapshots, range_end: range_end, closing: closing), snapshots]
176
209
  end
177
210
 
178
211
  #: () -> [RecordSnapshot?, untyped]
@@ -187,7 +220,6 @@ module PaperTrailDiff
187
220
  end
188
221
 
189
222
  Endpoint.validate_pair!(@range.from, @to)
190
- reject_live_habtm!
191
223
  end
192
224
 
193
225
  # A window with no selected event reports nothing, and so does one whose
@@ -199,25 +231,52 @@ module PaperTrailDiff
199
231
  # A window closing on current state runs to the instant it is captured,
200
232
  # not to the last root version, or descendants that moved after that
201
233
  # version would be missing from a report that claims to reach now.
234
+ #
235
+ # The events are read from where the transactions across the window's
236
+ # start began, and replayed whole; the window reports those whose
237
+ # transactions end inside it. The live record is read only once something
238
+ # in the window is reported.
202
239
  #: () -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
203
240
  def window_replay
204
- plan = select_plan
205
- live = plan.closing_record
206
- reject_live_habtm! if live
207
- window_activity(plan, live, (Time.now.utc if live)) unless plan.empty? && !live
208
- end
241
+ read = window_events
242
+ return unless read
209
243
 
210
- # The live record is read only once something in the window is reported.
211
- #: (RootVersionPlan, untyped, untyped) -> [RootVersionPlan, ActivityHistory, Array[ActivityStep], RecordSnapshot?, RecordSnapshot?, untyped]?
212
- def window_activity(plan, live, captured_at)
213
- events, snapshots = range_events(plan, captured_at)
244
+ wide, events, snapshots, captured_at = read
245
+
246
+ ends = @ends #: TransactionEnds
247
+ plan = @range.reporting_plan(wide, ends, context_required: true)
214
248
  return unless events.any? { |event| reported?(event, plan) }
215
249
 
250
+ live = wide.closing_record
216
251
  snapshot = (@snapshotter.call(live, live) if live)
217
- history = replay(plan, events, snapshots, current: live, closing: snapshot)
252
+ history = replay(plan, wide, events, snapshots, current: live, closing: snapshot)
218
253
  live_replay(plan, history, live, captured_at, snapshot)
219
254
  end
220
255
 
256
+ # The plan of every root version the window's transactions saved, its
257
+ # events, their history, and when the live record it closes on was read;
258
+ # nil when there is nothing to replay. The window is planned and read
259
+ # from where the earliest transaction open at its start began, which may
260
+ # have destroyed a root that has no version in the window itself. A
261
+ # batch has planned and read its roots so already.
262
+ #: () -> [RootVersionPlan, Array[ActivityEvent], untyped, untyped]?
263
+ def window_events
264
+ reach = (@snapshotter.reach_before(@record, @range.begin_time) unless @range.preselected?)
265
+ wide = reach ? @range.reach_plan(reach, context_required: true) : select_plan
266
+ return if wide.empty? && !wide.closing_record
267
+
268
+ events, snapshots, captured_at = events_through(wide, start_at: reach || @range.begin_time)
269
+ [wide, events, snapshots, captured_at]
270
+ end
271
+
272
+ #: (RootVersionPlan, **untyped) -> [Array[ActivityEvent], untyped, untyped]
273
+ def events_through(wide, **options)
274
+ live = wide.closing_record
275
+ captured_at = (Time.now.utc if live)
276
+ events, snapshots = range_events(wide, captured_at, **options)
277
+ [events, snapshots, captured_at]
278
+ end
279
+
221
280
  # The step that closes the range after its last event, which is reported
222
281
  # as that event's step would be. It runs from the last boundary the
223
282
  # history kept into one no version can supply: the live record the range
@@ -258,39 +317,31 @@ module PaperTrailDiff
258
317
  end
259
318
  end
260
319
 
261
- #: () -> void
262
- def reject_live_habtm!
263
- @traversal.reject_live_habtm_activity!(@record.class)
264
- end
265
-
266
320
  #: () -> RecordedChangesReader?
267
321
  def root_recorded
268
322
  @view.recorded_reader(root: true)
269
323
  end
270
324
 
271
- # A window prepares from its start, explicit endpoints from their first
272
- # version.
273
- #: (Array[untyped], end_at: untyped) -> untyped
274
- def prepare_history(root_versions, end_at:)
275
- options = { start_at: @range.begin_time, end_at: end_at }.compact
276
- @snapshotter.prepare(@record, root_versions, **options)
277
- end
278
-
279
- # A window collects from its start, explicit endpoints from their first
280
- # version. Explicit endpoints also stop before the rest of the closing
281
- # version's transaction (see ActivityTransactionGroups.before_closing); a
282
- # window keeps every event it collected and reports only those inside it.
283
- #: (Array[untyped], untyped, range_end: untyped) -> Array[ActivityEvent]
284
- def collect_events(root_versions, snapshots, range_end:)
285
- events = ActivityVersionCollector.new(
325
+ # Events are collected from where the history starts, which is where the
326
+ # transactions across the range's start began. Without a history only
327
+ # root versions are collected, all of them in the range. Explicit
328
+ # endpoints also stop before the rest of the closing version's
329
+ # transaction (see ActivityTransactionGroups.before_closing); a window
330
+ # keeps every event it collected and reports only those inside it.
331
+ #: (Array[untyped], untyped, range_end: untyped, closing: untyped) -> Array[ActivityEvent]
332
+ def collect_events(root_versions, snapshots, range_end:, closing:)
333
+ collector = ActivityVersionCollector.new(
286
334
  @record,
287
335
  root_versions: root_versions,
288
336
  traversal: @traversal,
289
337
  prepared: snapshots.activity_index,
290
- range_start: @range.begin_time || root_versions.first,
338
+ range_start: snapshots.history&.start_time,
291
339
  range_end: range_end
292
- ).call
293
- events = ActivityTransactionGroups.before_closing(events, range_end) unless @range.time?
340
+ )
341
+ events = collector.call
342
+ @ends = collector.ends
343
+ events = ActivityTransactionGroups.before_closing(events, closing) unless @range.time?
344
+ events = ActivityTransactionGroups.until_destroyed(events)
294
345
  prepare_filter(snapshots, events)
295
346
  events
296
347
  end
@@ -305,15 +356,20 @@ module PaperTrailDiff
305
356
  # Events after the last root version read the root from the live record
306
357
  # when the range closes on it. Explicit endpoints report every step their
307
358
  # plan does, as their range includes every version.
308
- #: (RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
309
- def replay(plan, events, snapshots, current:, closing:)
359
+ # `wide` holds every root version among the events, which a window's plan
360
+ # need not.
361
+ #: (RootVersionPlan, RootVersionPlan, Array[ActivityEvent], untyped, current: untyped, closing: RecordSnapshot?) -> ActivityHistory
362
+ def replay(plan, wide, events, snapshots, current:, closing:) # rubocop:disable Metrics/ParameterLists
363
+ ends = @ends #: TransactionEnds
310
364
  ActivityHistoryBuilder.new(
311
- plan.reconstruction_versions, events, snapshots,
365
+ wide.reconstruction_versions, events, snapshots,
312
366
  current: current,
313
367
  include_step: ->(event) { reported?(event, plan) },
314
368
  view: @view,
315
369
  closing: closing,
316
- root: root_reference
370
+ root: root_reference,
371
+ ends: ends,
372
+ filtered: !@filter.nil?
317
373
  ).call
318
374
  end
319
375
 
@@ -326,10 +382,5 @@ module PaperTrailDiff
326
382
  def root_reference
327
383
  RecordReference.new(type: @record.class.name, id: @record.id)
328
384
  end
329
-
330
- #: (Array[ActivityStep]) -> Array[ActivityStep]
331
- def present(steps)
332
- @view.present(steps).freeze
333
- end
334
385
  end
335
386
  end
@@ -0,0 +1,49 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Applies the versions of one transaction to a snapshot, each to the record
6
+ # it saved, as a version alone in its transaction is applied. A transaction's
7
+ # changes appear together at the event after its last, so the snapshot there
8
+ # is the one before it with every one of its versions applied; reading the
9
+ # branches again instead costs every record in them.
10
+ class ActivityTransactionApplier
11
+ #: (ActivityEventSnapshotRefresher, ActivityRootSnapshotRefresher) -> void
12
+ def initialize(event_refresher, root_refresher)
13
+ @event_refresher = event_refresher
14
+ @root_refresher = root_refresher
15
+ end
16
+
17
+ # nil when any event cannot be applied to the snapshot alone. Applying
18
+ # only some would leave a record as no version left it.
19
+ #: (untyped, untyped, RecordSnapshot, Array[ActivityEvent]) -> RecordSnapshot?
20
+ def call(root_endpoint, context_endpoint, snapshot, events)
21
+ events.reduce(snapshot) do |carried, event|
22
+ handled, incremental = apply(root_endpoint, context_endpoint, carried, event)
23
+ break unless handled && incremental
24
+
25
+ incremental
26
+ end
27
+ end
28
+
29
+ private
30
+
31
+ # @rbs @event_refresher: ActivityEventSnapshotRefresher
32
+ # @rbs @root_refresher: ActivityRootSnapshotRefresher
33
+
34
+ # A record on several branches is applied on each.
35
+ #: (untyped, untyped, RecordSnapshot, ActivityEvent) -> [bool, RecordSnapshot?]
36
+ def apply(root_endpoint, context_endpoint, snapshot, event)
37
+ return @root_refresher.call(root_endpoint, context_endpoint, snapshot, event) if event.root?
38
+
39
+ branches = event.branches #: Array[String]
40
+ branches.reduce([true, snapshot]) do |(_, carried), branch|
41
+ handled, incremental = @event_refresher.call(root_endpoint, context_endpoint, carried,
42
+ [branch], event)
43
+ break [false, nil] unless handled
44
+
45
+ [true, incremental || carried]
46
+ end
47
+ end
48
+ end
49
+ end