paper_trail_diff 0.15.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -15,14 +15,31 @@ module PaperTrailDiff
15
15
  # Only the root's own versions on either side of an edge are consulted:
16
16
  # rows locked by an update keep two transactions of one root from
17
17
  # interleaving, so a transaction holding a root version and crossing the edge
18
- # holds the root's nearest version on one side of it. Each edge is moved from
19
- # where it was asked for, never from where another edge moved, so adjacent
20
- # windows move their shared edge alike.
21
- module TransactionCut
18
+ # holds the root's nearest version on one side of it. One that saved the root
19
+ # after the edge moves it. One that saved the root only before the edge moves
20
+ # it only when it saved a record of a type on the requested paths after it,
21
+ # which the root's history reads: without one, the root's change is in the
22
+ # earlier window, where its version is, as selecting by a window's versions
23
+ # finds it, and ScopedRootSelection selects the roots such a move brings into
24
+ # a window. Each edge is moved from where it was asked for, never from where
25
+ # another edge moved, so adjacent windows move their shared edge alike.
26
+ module TransactionCut # rubocop:disable Metrics/ModuleLength
22
27
  # One edge of a window. A strict edge keeps versions recorded at its
23
28
  # instant on the left, as an inclusive end does. A plain class rather than
24
29
  # Data.define, which arrived in Ruby 3.2 while this gem supports 3.1.
25
30
  class Edge
31
+ # A window's start, which keeps versions recorded at it on the right.
32
+ #: (TimeRange) -> Edge
33
+ def self.start_of(range) = new(range.begin_time, false)
34
+
35
+ # A window's end, strict when the window includes it; an endless window
36
+ # has none.
37
+ #: (TimeRange) -> Edge?
38
+ def self.end_of(range)
39
+ finish = range.end_time
40
+ new(finish, !range.exclude_end?) if finish
41
+ end
42
+
26
43
  #: (Time, bool) -> void
27
44
  def initialize(time, strict)
28
45
  @time = time
@@ -40,29 +57,19 @@ module PaperTrailDiff
40
57
  @strict ? column.gt(@time) : column.gteq(@time)
41
58
  end
42
59
 
43
- #: (untyped, later: bool) -> untyped
44
- def side(column, later:)
45
- later ? right(column) : left(column)
46
- end
47
-
48
60
  # @rbs @time: Time
49
61
  # @rbs @strict: bool
50
62
  end
51
63
 
52
- # Roots per statement: two lookups each stays under SQLite's limit of 500
53
- # terms in a compound SELECT.
54
- SLICE = 200
55
- private_constant :SLICE
56
-
57
64
  # The same as `windows` for a batch of roots, keyed by identity.
58
- #: (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
59
- def self.batch_windows(records, range)
65
+ #: (Array[untyped], TimeRange?, ?traversal: AssociationTraversal?) -> Hash[Array[String], TimeRange]
66
+ def self.batch_windows(records, range, traversal: nil)
60
67
  return {} unless range
61
68
 
62
69
  moved = {} #: Hash[Array[String], TimeRange]
63
70
  records.group_by(&:class).each_with_object(moved) do |(model_class, group), by_identity|
64
71
  identities = group.to_h { |record| [record.id.to_s, Endpoint.identity(record)] }
65
- windows(model_class, group, range).each do |id, window|
72
+ windows(model_class, group, range, traversal: traversal).each do |id, window|
66
73
  by_identity[identities.fetch(id)] = window
67
74
  end
68
75
  end
@@ -77,97 +84,250 @@ module PaperTrailDiff
77
84
  end
78
85
 
79
86
  # The windows that move, keyed by root id. A root missing from the result
80
- # keeps the window as asked.
81
- #: (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
82
- def self.windows(model_class, records, range)
87
+ # keeps the window as asked. `traversal` names the requested paths.
88
+ # `records` may be ids. Each move is reported unless `report` is false,
89
+ # for a reader that looks before the analysis that reports them.
90
+ #: (untyped, Array[untyped], TimeRange, ?traversal: AssociationTraversal?, ?report: bool) -> Hash[String, TimeRange]
91
+ def self.windows(model_class, records, range, traversal: nil, report: true)
83
92
  versions = transaction_versions(model_class)
84
93
  return {} unless versions
85
94
 
86
- starts = moved_edges(versions, records, Edge.new(range.begin_time, false))
87
- ends = moved_edges(versions, records, Edge.new(range.end_time, !range.exclude_end?))
88
- (starts.keys | ends.keys).to_h { |id| [id, moved(range, starts[id], ends[id])] }
95
+ types = traversal&.path_types(model_class) || []
96
+ starts = moved_edges(versions, records, Edge.start_of(range), types)
97
+ finish = Edge.end_of(range)
98
+ ends = finish ? moved_edges(versions, records, finish, types) : {} #: Hash[String, Time]
99
+ (starts.keys | ends.keys).to_h do |id|
100
+ window = moved(range, starts[id], ends[id])
101
+ report_move(model_class, id, range, window) if report
102
+ [id, window]
103
+ end
104
+ end
105
+
106
+ # Reads the windows of `model_class` ids for a range, unreported.
107
+ #: (untyped, AssociationTraversal?) -> ^(Array[String], TimeRange) -> Hash[String, TimeRange]
108
+ def self.reader(model_class, traversal)
109
+ ->(ids, range) { windows(model_class, ids, range, traversal: traversal, report: false) }
110
+ end
111
+
112
+ # A transaction holds its rows only while it runs, so in history as an
113
+ # application saves it an edge moves by moments. A longer move means a
114
+ # long transaction or rewritten times, which only the application can
115
+ # judge, so each move is reported rather than logged or refused.
116
+ #: (untyped, String, TimeRange, TimeRange) -> void
117
+ def self.report_move(model_class, id, range, window)
118
+ Instrumentation.notify(
119
+ 'moved_window',
120
+ item_type: model_class.base_class.name, item_id: id,
121
+ requested: range.to_range, window: window.to_range
122
+ )
123
+ end
124
+ private_class_method :report_move
125
+
126
+ # The model's versions in a window, and those saved before it in a
127
+ # transaction that saved a record of one of `types` inside it, which
128
+ # moves their root's window back to take them in: the versions that
129
+ # select a root for the window. Without a window, every version does.
130
+ #: (untyped, TimeRange?, Array[String]) -> untyped
131
+ def self.window_versions(model_class, range, types)
132
+ versions = VersionQuery.for_model(model_class)
133
+ return versions unless range
134
+
135
+ inside = range.scope(versions)
136
+ version_class = model_class.paper_trail.version_class
137
+ return inside if types.empty? || !transactional?(version_class)
138
+
139
+ inside.or(crossing_versions(versions, version_class, range, types))
89
140
  end
90
141
 
142
+ #: (untyped, untyped, TimeRange, Array[String]) -> untyped
143
+ def self.crossing_versions(versions, version_class, range, types)
144
+ transactions = range.scope(version_class.where(item_type: types)).select(:transaction_id)
145
+ versions.where(version_class.arel_table[:created_at].lt(range.begin_time))
146
+ .where(transaction_id: transactions)
147
+ end
148
+ private_class_method :crossing_versions
149
+
91
150
  #: (untyped) -> untyped
92
151
  def self.transaction_versions(model_class)
93
- return unless model_class.paper_trail.version_class.column_names.include?('transaction_id')
94
-
95
- VersionQuery.for_model(model_class)
152
+ VersionQuery.for_model(model_class) if transactional?(model_class.paper_trail.version_class)
96
153
  end
97
154
  private_class_method :transaction_versions
98
155
 
99
- # Each root's earliest start among its transactions that cross the edge.
100
- #: (untyped, Array[untyped], Edge) -> Hash[String, Time]
101
- def self.moved_edges(versions, records, edge)
102
- roots = nearest_roots(versions, records, edge)
156
+ #: (untyped) -> bool
157
+ def self.transactional?(version_class)
158
+ version_class.column_names.include?('transaction_id')
159
+ end
160
+ private_class_method :transactional?
161
+
162
+ # Each root's earliest start among its transactions that cross the edge:
163
+ # the one that saved its first version after the edge, which crosses when
164
+ # it began before it, and the one that saved its last version before it,
165
+ # which crosses when it saved a record of one of `types` after it.
166
+ #: (untyped, Array[untyped], Edge, Array[String]) -> Hash[String, Time]
167
+ def self.moved_edges(versions, records, edge, types)
103
168
  moved = {} #: Hash[String, Time]
104
- starts = crossing_starts(versions.klass, roots.keys, edge)
105
- starts.each_with_object(moved) do |(transaction, start), edges|
106
- roots.fetch(transaction).each { |id| edges[id] = [edges[id], start].compact.min }
169
+ crossing(versions, records, edge, types).each_with_object(moved) do |(roots, starts), found|
170
+ starts.each do |transaction, start|
171
+ roots.fetch(transaction).each { |id| found[id] = [found[id], start].compact.min }
172
+ end
107
173
  end
108
174
  end
109
175
  private_class_method :moved_edges
110
176
 
111
- # The roots whose versions next to the edge each transaction holds.
112
- #: (untyped, Array[untyped], Edge) -> Hash[untyped, Array[String]]
177
+ # For each side of the edge, the roots its transactions hold next to the
178
+ # edge, and where those that cross it began.
179
+ #: (untyped, Array[untyped], Edge, Array[String]) -> Array[[Hash[untyped, Array[String]], Hash[untyped, Time]]]
180
+ def self.crossing(versions, records, edge, types)
181
+ later, earlier = nearest_roots(versions, records, edge)
182
+ # @type var sides: Array[[Hash[untyped, Array[String]], Hash[untyped, Time]]]
183
+ sides = [[later, crossing_starts(versions.klass, later.keys, edge)]]
184
+ return sides if types.empty?
185
+
186
+ sides << [earlier, crossing_starts(versions.klass, earlier.keys, edge, types)]
187
+ end
188
+ private_class_method :crossing
189
+
190
+ # The roots whose versions next to the edge each transaction holds, those
191
+ # after the edge and those before it.
192
+ #: (untyped, Array[untyped], Edge) -> [Hash[untyped, Array[String]], Hash[untyped, Array[String]]]
113
193
  def self.nearest_roots(versions, records, edge)
114
- records.each_slice(SLICE).flat_map { |slice| nearest(versions, slice, edge) }
115
- .group_by(&:last).transform_values { |pairs| pairs.map(&:first) }
194
+ # The lookup names its ids twice in one statement, for the grouped instants
195
+ # and for the versions they join, so half a statement's ids keep it under
196
+ # 1,000 bound parameters, the most SQLite allowed before 3.32.
197
+ rows = records.each_slice(Support::IDS_PER_STATEMENT / 2).flat_map do |slice|
198
+ nearest(versions, slice, edge)
199
+ end
200
+ later, earlier = rows.partition(&:last)
201
+ [by_transaction(later), by_transaction(earlier)]
116
202
  end
117
203
  private_class_method :nearest_roots
118
204
 
205
+ # The roots of the rows, by the transaction each row names.
206
+ #: (Array[[String, untyped, bool]]) -> Hash[untyped, Array[String]]
207
+ def self.by_transaction(rows)
208
+ rows.group_by { |row| row.fetch(1) }.transform_values { |group| group.map(&:first) }
209
+ end
210
+ private_class_method :by_transaction
211
+
119
212
  # Each root's nearest versions on either side of an edge, as [id,
120
- # transaction] pairs; versions tied at the nearest instant are all kept.
121
- # One indexed lookup per root and side, where a single query over the
122
- # roots would read every version before the edge. The lookups are written
123
- # once with the root's id left open, as building a relation for each root
124
- # costs more than the query. Rows read as SQL text come back as the adapter
125
- # returns them, so the transaction is cast as the grouped query's keys are.
126
- #: (untyped, Array[untyped], Edge) -> Array[[String, untyped]]
213
+ # transaction, after the edge] rows; versions tied at the nearest instant
214
+ # are all kept. One statement per slice: a grouped pass over the roots'
215
+ # versions finds both instants, and a join reads the versions saved at
216
+ # either. A lookup per root, joined by UNION ALL, took SQL Server about a
217
+ # second per 200 roots to compile. Rows read without a model come back as
218
+ # the adapter returns them, so the transaction is cast as the grouped
219
+ # query's keys are.
220
+ #
221
+ # The ids go to the adapter as bound parameters. Written into the
222
+ # statement, they made each slice's text new to SQL Server, which compiled
223
+ # it again, at about 0.05 ms per id.
224
+ #: (untyped, Array[untyped], Edge) -> Array[[String, untyped, bool]]
127
225
  def self.nearest(versions, records, edge)
128
- lookup = nearest_lookups(versions, edge)
129
- item_id = versions.type_for_attribute('item_id')
130
- lookups = records.map do |record|
131
- versions.sanitize_sql_array([lookup, *Array.new(4, item_id.serialize(record.id))])
132
- end
133
226
  transaction = versions.type_for_attribute('transaction_id')
134
- versions.connection.select_rows(lookups.join(' UNION ALL ')).map do |id, value|
135
- [id.to_s, transaction.cast(value)]
136
- end
227
+ rows = versions.connection.select_rows(nearest_query(versions, records, edge))
228
+ rows.map { |id, value, flag| [id.to_s, transaction.cast(value), after_edge?(flag)] }
137
229
  end
138
230
  private_class_method :nearest
139
231
 
140
- # Both sides' lookups for a root whose id is each `?`.
141
- #: (untyped, Edge) -> String
142
- def self.nearest_lookups(versions, edge)
143
- own = versions.where("#{versions.quoted_table_name}.item_id = ?")
144
- "#{nearest_lookup(own, edge, false)} UNION ALL #{nearest_lookup(own, edge, true)}"
232
+ # The roots' versions saved in a transaction at either nearest instant,
233
+ # each with whether it is the one after the edge.
234
+ #: (untyped, Array[untyped], Edge) -> untyped
235
+ def self.nearest_query(versions, records, edge)
236
+ own = versions.where(item_id: records)
237
+ table = own.arel_table
238
+ instants = nearest_instants(own, edge)
239
+ own.joins(Support.arel::Nodes::InnerJoin.new(instants, at_either(table, instants)))
240
+ .where.not(transaction_id: nil)
241
+ .select(table[:item_id], table[:transaction_id], after_edge(table, instants)).arel
242
+ end
243
+ private_class_method :nearest_query
244
+
245
+ # 1 for a version saved at the instant after the edge, 0 for one before.
246
+ # Only the 1 is read (see after_edge?), so another value or alias, or none,
247
+ # answers the same.
248
+ # mutant:disable
249
+ #: (untyped, untyped) -> untyped
250
+ def self.after_edge(table, instants)
251
+ Support.arel::Nodes::Case.new.when(table[:created_at].eq(instants[:after_at]))
252
+ .then(1).else(0).as('after_edge')
253
+ end
254
+ private_class_method :after_edge
255
+
256
+ # Whether after_edge flagged a row as saved after the edge. Adapters
257
+ # return the flag as an Integer or a String, so any spelling that reads
258
+ # only 1 as after answers the same.
259
+ # mutant:disable
260
+ #: (untyped) -> bool
261
+ def self.after_edge?(flag)
262
+ flag.to_i == 1
263
+ end
264
+ private_class_method :after_edge?
265
+
266
+ # Each root's latest instant before the edge and earliest after it, from
267
+ # every version, saved in a transaction or not.
268
+ #: (untyped, Edge) -> untyped
269
+ def self.nearest_instants(own, edge)
270
+ table = own.arel_table
271
+ column = table[:created_at]
272
+ nodes = Support.arel::Nodes
273
+ before = side_instant(nodes::Max, edge.left(column), column).as('before_at')
274
+ after = side_instant(nodes::Min, edge.right(column), column).as('after_at')
275
+ own.group(:item_id).select(table[:item_id], before, after).arel.as('paper_trail_diff_nearest')
145
276
  end
146
- private_class_method :nearest_lookups
277
+ private_class_method :nearest_instants
147
278
 
148
- #: (untyped, Edge, bool) -> String
149
- def self.nearest_lookup(own, edge, later)
150
- column = own.arel_table[:created_at]
151
- instant = own.where(edge.side(column, later: later))
152
- .reorder(created_at: later ? :asc : :desc).limit(1).select(:created_at)
153
- own.where(column.eq(instant.arel)).where.not(transaction_id: nil)
154
- .select(:item_id, :transaction_id).to_sql
279
+ # The latest or earliest of the times on one side of the edge.
280
+ #: (untyped, untyped, untyped) -> untyped
281
+ def self.side_instant(aggregate, side, column)
282
+ aggregate.new([Support.arel::Nodes::Case.new.when(side).then(column)])
155
283
  end
156
- private_class_method :nearest_lookup
284
+ private_class_method :side_instant
157
285
 
158
- # Where each transaction that has versions on both sides of the edge began.
159
- #: (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
160
- def self.crossing_starts(version_class, transactions, edge)
161
- return {} if transactions.empty?
286
+ # The same root's versions saved at either of its instants.
287
+ #: (untyped, untyped) -> untyped
288
+ def self.at_either(table, instants)
289
+ column = table[:created_at]
290
+ at_either = column.eq(instants[:before_at]).or(column.eq(instants[:after_at]))
291
+ Support.arel::Nodes::On.new(table[:item_id].eq(instants[:item_id]).and(at_either))
292
+ end
293
+ private_class_method :at_either
162
294
 
163
- column = version_class.arel_table[:created_at]
164
- scope = version_class.where(transaction_id: transactions)
165
- scope.where(edge.left(column))
166
- .where(transaction_id: scope.where(edge.right(column)).select(:transaction_id))
167
- .group(:transaction_id).minimum(:created_at)
295
+ # Where each transaction that saved a version before the edge began; with
296
+ # `types`, only one that also saved a record of one of them after it.
297
+ #: (untyped, Array[untyped], Edge, ?Array[String]?) -> Hash[untyped, Time]
298
+ def self.crossing_starts(version_class, transactions, edge, types = nil)
299
+ table = version_class.arel_table
300
+ earlier = edge.left(table[:created_at])
301
+ starts = {} #: Hash[untyped, Time]
302
+ transactions.each_slice(Support::IDS_PER_STATEMENT).with_object(starts) do |slice, found|
303
+ crossing = version_class.where(transaction_id: slice).where(earlier)
304
+ if types
305
+ crossing = crossing.where(transaction_id: saved_later(version_class, slice, edge, types))
306
+ end
307
+ found.merge!(crossing.group(:transaction_id).minimum(:created_at))
308
+ end
168
309
  end
169
310
  private_class_method :crossing_starts
170
311
 
312
+ # Those of the transactions that saved a version of a record of one of
313
+ # `types` on the edge's later side. A subquery apart from the outer one,
314
+ # rather than an EXISTS correlated with it, so the database finds them
315
+ # once by transaction: SQLite answered the correlated form by scanning
316
+ # every later version of the types for each version before the edge, with
317
+ # the README's indexes 17 s for 450 transactions on 114,000 versions.
318
+ # Only the outer query's transactions are read, so the database can find
319
+ # them by transaction rather than read every later version of the types;
320
+ # the outer query keeps only those anyway, so no spec can tell the
321
+ # mutation that drops them apart.
322
+ # mutant:disable
323
+ #: (untyped, Array[untyped], Edge, Array[String]) -> untyped
324
+ def self.saved_later(version_class, transactions, edge, types)
325
+ version_class.where(transaction_id: transactions, item_type: types)
326
+ .where(edge.right(version_class.arel_table[:created_at]))
327
+ .select(:transaction_id)
328
+ end
329
+ private_class_method :saved_later
330
+
171
331
  #: (TimeRange, Time?, Time?) -> TimeRange
172
332
  def self.moved(range, start, finish)
173
333
  begin_time = start || range.begin_time
@@ -48,21 +48,18 @@ module PaperTrailDiff
48
48
  # models it goes through, so each of them needs history too.
49
49
  #: (untyped) -> Array[untyped]
50
50
  def self.through_models(reflection)
51
- return [] unless reflection.through_reflection?
52
-
53
- [reflection.through_reflection, reflection.source_reflection].flat_map do |part|
54
- part.polymorphic? ? through_models(part) : [part.klass, *through_models(part)]
55
- end.uniq - [reflection.klass]
51
+ parts = AssociationTraversal.through_parts(reflection).reject(&:polymorphic?)
52
+ parts.map(&:klass).uniq - [reflection.klass]
56
53
  end
57
54
  private_class_method :through_models
58
55
 
59
- #: (tree: AssociationTree, traversal: AssociationTraversal, ?allow_approximate: bool) -> void
60
- def initialize(tree:, traversal:, allow_approximate: false)
56
+ #: (traversal: AssociationTraversal, ?allow_approximate: bool) -> void
57
+ def initialize(traversal:, allow_approximate: false)
61
58
  unless [true, false].include?(allow_approximate)
62
59
  raise ConfigurationError, 'allow_approximate: must be true or false'
63
60
  end
64
61
 
65
- @tree = tree
62
+ @tree = traversal.tree
66
63
  @traversal = traversal
67
64
  @allow_approximate = allow_approximate
68
65
  @refusals = {} #: Hash[Array[untyped], Array[Refusal]]
@@ -34,7 +34,10 @@ module PaperTrailDiff
34
34
  #
35
35
  # An element that is itself a Hash or Array is reported whole. Saying which
36
36
  # field of which object changed would require pairing before-elements with
37
- # after-elements, and nothing in the value licenses that pairing.
37
+ # after-elements, and nothing in the value licenses that pairing. Elements
38
+ # match with their keys read as strings (NestedComparator.comparable), so
39
+ # `{a: 1}` and `{"a" => 1}` are one element; each is reported as it was
40
+ # given.
38
41
  class ArrayChange
39
42
  attr_reader :from #: Array[untyped]
40
43
  attr_reader :to #: Array[untyped]
@@ -55,9 +58,9 @@ module PaperTrailDiff
55
58
  # rather than none.
56
59
  #: (Array[untyped], Array[untyped]) -> Array[untyped]
57
60
  def self.surplus(left, right)
58
- pool = right.dup
61
+ pool = right.map { |item| NestedComparator.comparable(item) }
59
62
  left.reject do |item|
60
- index = pool.index(item)
63
+ index = pool.index(NestedComparator.comparable(item))
61
64
  index ? pool.delete_at(index) || true : false
62
65
  end
63
66
  end
@@ -69,9 +72,10 @@ module PaperTrailDiff
69
72
  added.empty? && removed.empty?
70
73
  end
71
74
 
75
+ # The same elements in the same order, with keys read as strings.
72
76
  #: () -> bool
73
77
  def empty?
74
- from == to
78
+ NestedComparator.comparable(from) == NestedComparator.comparable(to)
75
79
  end
76
80
 
77
81
  #: () -> Hash[Symbol, untyped]
@@ -2,5 +2,5 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- VERSION = '0.15.0'
5
+ VERSION = '0.17.0'
6
6
  end
@@ -24,20 +24,9 @@ module PaperTrailDiff
24
24
  # @rbs @start_at: untyped
25
25
  # @rbs @end_at: untyped
26
26
 
27
- # Only quoting helpers are needed, so the connection is borrowed for the
28
- # duration of building the condition rather than checked out permanently,
29
- # which Active Record 7.2 and newer can deprecate. Active Record 7.1 has no
30
- # `with_connection` and reaches the same connection through the accessor.
31
- #: () { (untyped) -> String } -> String
32
- def with_connection(&block)
33
- return @version_class.with_connection(&block) if @version_class.respond_to?(:with_connection)
34
-
35
- yield(@version_class.connection)
36
- end
37
-
38
27
  #: () -> String
39
28
  def candidate_condition
40
- with_connection { |connection| condition_sql(connection) }
29
+ Support.with_connection(@version_class) { |connection| condition_sql(connection) }
41
30
  end
42
31
 
43
32
  #: (untyped) -> String
@@ -4,17 +4,20 @@
4
4
  module PaperTrailDiff
5
5
  # Places one version relative to another on the recorded timeline.
6
6
  module VersionBoundary
7
- module_function
7
+ @transactional = {} #: Hash[untyped, bool]
8
+ @version_records = {} #: Hash[untyped, bool]
8
9
 
9
10
  # Whether `candidate` was recorded at or after `boundary`. Versions sharing
10
11
  # a timestamp are ordered by id, which reflects insertion order only for
11
12
  # sequential ids in one version table; any other tie cannot be ordered, and
12
13
  # guessing would place a change on an arbitrary side of the boundary. A
13
14
  # bare instant has no position among same-time versions, so it keeps them.
14
- #: (untyped, untyped) -> bool
15
- def at_or_after?(candidate, boundary)
16
- tied = candidate.created_at == boundary.created_at
17
- return candidate.created_at > boundary.created_at unless tied
15
+ # `time` and `boundary_time` are when each was recorded, which a caller
16
+ # placing many versions against one boundary reads once.
17
+ #: (untyped, untyped, ?time: untyped, ?boundary_time: untyped) -> bool
18
+ def self.at_or_after?(candidate, boundary, time: candidate.created_at,
19
+ boundary_time: boundary.created_at)
20
+ return time > boundary_time unless time == boundary_time
18
21
  return true unless version_record?(boundary)
19
22
  return true if same_version?(candidate, boundary)
20
23
 
@@ -22,7 +25,8 @@ module PaperTrailDiff
22
25
  raise AmbiguousVersionOrderError, Support.ambiguous_message([boundary, candidate])
23
26
  end
24
27
 
25
- Support.compare_versions(candidate, boundary) >= 0
28
+ # Different rows of one table, so one id comes after the other.
29
+ Support.compare_versions(candidate, boundary).positive?
26
30
  end
27
31
 
28
32
  # A range starting at a version starts before that version's transaction,
@@ -31,25 +35,25 @@ module PaperTrailDiff
31
35
  # version, can be recorded before the start, so the start moves back to
32
36
  # the earliest version of each root's first transaction in the range.
33
37
  # History loaded from the start alone would read that child after its
34
- # change.
38
+ # change. The transactions go 500 to a statement.
35
39
  #: (Array[untyped], untyped) -> untyped
36
- def transaction_start(root_versions, start_at)
37
- opening = opening_transactions(root_versions, start_at)
38
- return start_at if opening.empty?
39
-
40
- earliest = root_versions.first.class.where(transaction_id: opening).minimum(:created_at)
40
+ def self.transaction_start(root_versions, start_at)
41
+ earliest = opening_transactions(root_versions, start_at)
42
+ .each_slice(Support::IDS_PER_STATEMENT).filter_map do |slice|
43
+ root_versions.first.class.where(transaction_id: slice).minimum(:created_at)
44
+ end.min
41
45
  earliest && earliest < start_at ? earliest : start_at
42
46
  end
43
47
 
44
48
  # The transaction of each root's first version at or after the start.
45
49
  #: (Array[untyped], untyped) -> Array[untyped]
46
- def opening_transactions(root_versions, start_at)
50
+ def self.opening_transactions(root_versions, start_at)
47
51
  return [] unless start_at
48
52
 
49
53
  root_versions.reject { |version| version.created_at < start_at }
50
54
  .sort_by { |version| Support.chronological_version_key(version) }
51
- .uniq { |version| [version.item_type.to_s, version.item_id.to_s] }
52
- .filter_map { |version| transaction_id(version) }.uniq
55
+ .uniq { |version| Endpoint.identity(version) }
56
+ .filter_map { |version| transaction_id(version) }
53
57
  end
54
58
  private_class_method :opening_transactions
55
59
 
@@ -57,21 +61,35 @@ module PaperTrailDiff
57
61
  # it nil outside a transaction. Both read as "no transaction here", which
58
62
  # groups with nothing.
59
63
  #: (untyped) -> untyped
60
- def transaction_id(version)
61
- version.transaction_id if version.respond_to?(:transaction_id)
64
+ def self.transaction_id(version)
65
+ version.transaction_id if transactional?(version)
66
+ end
67
+
68
+ # Answered once for each Active Record class (see Support.per_model).
69
+ #: (untyped) -> bool
70
+ def self.transactional?(version)
71
+ known = @transactional #: Hash[untyped, bool]
72
+ Support.per_model(known, version) { |value| value.respond_to?(:transaction_id) }
62
73
  end
74
+ private_class_method :transactional?
63
75
 
76
+ # Answered once for each Active Record class, as `transactional?` is.
64
77
  #: (untyped) -> bool
65
- def version_record?(value)
66
- value.respond_to?(:id) && value.respond_to?(:item_type) &&
67
- value.class.respond_to?(:table_name)
78
+ def self.version_record?(value)
79
+ known = @version_records #: Hash[untyped, bool]
80
+ Support.per_model(known, value) do |candidate|
81
+ candidate.respond_to?(:id) && candidate.respond_to?(:item_type) &&
82
+ candidate.class.respond_to?(:table_name)
83
+ end
68
84
  end
69
85
  private_class_method :version_record?
70
86
 
87
+ # The same row of the same version table. A record or instant is never a
88
+ # version.
71
89
  #: (untyped, untyped) -> bool
72
- def same_version?(left, right)
73
- left.class.table_name == right.class.table_name && left.id.to_s == right.id.to_s
90
+ def self.same_version?(left, right)
91
+ version_record?(left) && version_record?(right) &&
92
+ left.class.table_name == right.class.table_name && left.id.to_s == right.id.to_s
74
93
  end
75
- private_class_method :same_version?
76
94
  end
77
95
  end