paper_trail_diff 0.16.0 → 0.17.1

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 +581 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -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 +3 -13
  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 +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -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 +74 -40
  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 +194 -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 +19 -5
  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 +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  44. data/lib/paper_trail_diff/change_attribution.rb +329 -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 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  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 +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +197 -45
  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 +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  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 +41 -19
  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 +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  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 +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -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 +192 -91
  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 +27 -16
  105. data/lib/paper_trail_diff/version_boundary.rb +37 -21
  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 +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  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 +0 -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 +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -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 +36 -2
  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 +121 -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 +15 -6
  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 +9 -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 +11 -5
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +194 -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 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  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 +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +114 -14
  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 +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  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 +27 -8
  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 +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  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 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -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 +111 -52
  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 +10 -9
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -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 +13 -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 +28 -6
  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
@@ -0,0 +1,55 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # A relation's order, completed by its primary key. Reading a relation by
6
+ # offset holds only under a total order: a database may return rows that tie
7
+ # in a different order for each query, so that pages read some records twice
8
+ # and others never.
9
+ module TotalOrder
10
+ # The relation sorted by its key after its own order, unless that order
11
+ # already sorts by the key. Such an order is kept as given, since SQL
12
+ # Server rejects a column listed twice. So is the order of a relation
13
+ # grouped by anything but the key: each of its rows is a group, which a
14
+ # database sorts only by what it groups or aggregates. A relation answers
15
+ # for its model the key and table name read here.
16
+ #: (untyped) -> untyped
17
+ def self.apply(relation)
18
+ orders = relation.order_values
19
+ return relation if orders.any? { |order| key?(order, relation) }
20
+ return relation if !orders.empty? && grouped_by_other?(relation)
21
+
22
+ relation.order(relation.primary_key => :asc)
23
+ end
24
+
25
+ #: (untyped) -> bool
26
+ def self.grouped_by_other?(relation)
27
+ groups = relation.group_values
28
+ !groups.empty? && groups.none? { |group| key?(group, relation) }
29
+ end
30
+ private_class_method :grouped_by_other?
31
+
32
+ # An Arel order or group names its column; SQL text, or the name a group
33
+ # may be given as, is read by key_in_sql?.
34
+ #: (untyped, untyped) -> bool
35
+ def self.key?(term, relation)
36
+ term = term.expr if ScopeRanking::DIRECTIONS.key?(term.class.name)
37
+ return key_in_sql?(term.to_s, relation) if term.is_a?(String) || term.instance_of?(Symbol)
38
+
39
+ relation.primary_key.eql?(ScopeRanking.own_column(term, relation))
40
+ end
41
+ private_class_method :key?
42
+
43
+ # Whether SQL text names the key, alone or after its table's name. That
44
+ # also finds a key the text only uses, as in `LENGTH(id)`, which then goes
45
+ # without the tie-breaker, but it misses no sort by the key.
46
+ #: (String, untyped) -> bool
47
+ def self.key_in_sql?(sql, relation)
48
+ names = sql.scan(/(?:(\w+)\.)?(\w+)/) #: Array[[String?, String]]
49
+ names.any? do |table, column|
50
+ column.casecmp?(relation.primary_key) && (table.nil? || table.casecmp?(relation.table_name))
51
+ end
52
+ end
53
+ private_class_method :key_in_sql?
54
+ end
55
+ end
@@ -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.
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.
21
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
@@ -44,21 +61,15 @@ module PaperTrailDiff
44
61
  # @rbs @strict: bool
45
62
  end
46
63
 
47
- # Roots, or transactions, per statement. SQL Server compiles every
48
- # statement afresh, since its ids are written into it, in time that grows
49
- # with their number; fewer statements than this cost more than they save.
50
- SLICE = 500
51
- private_constant :SLICE
52
-
53
64
  # The same as `windows` for a batch of roots, keyed by identity.
54
- #: (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
55
- 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)
56
67
  return {} unless range
57
68
 
58
69
  moved = {} #: Hash[Array[String], TimeRange]
59
70
  records.group_by(&:class).each_with_object(moved) do |(model_class, group), by_identity|
60
71
  identities = group.to_h { |record| [record.id.to_s, Endpoint.identity(record)] }
61
- windows(model_class, group, range).each do |id, window|
72
+ windows(model_class, group, range, traversal: traversal).each do |id, window|
62
73
  by_identity[identities.fetch(id)] = window
63
74
  end
64
75
  end
@@ -73,88 +84,184 @@ module PaperTrailDiff
73
84
  end
74
85
 
75
86
  # The windows that move, keyed by root id. A root missing from the result
76
- # keeps the window as asked.
77
- #: (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
78
- 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)
79
92
  versions = transaction_versions(model_class)
80
93
  return {} unless versions
81
94
 
82
- starts = moved_edges(versions, records, Edge.new(range.begin_time, false))
83
- ends = moved_edges(versions, records, Edge.new(range.end_time, !range.exclude_end?))
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]
84
99
  (starts.keys | ends.keys).to_h do |id|
85
- [id, moved_window(model_class, id, range, starts[id], ends[id])]
100
+ window = moved(range, starts[id], ends[id])
101
+ report_move(model_class, id, range, window) if report
102
+ [id, window]
86
103
  end
87
104
  end
88
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
+
89
112
  # A transaction holds its rows only while it runs, so in history as an
90
113
  # application saves it an edge moves by moments. A longer move means a
91
114
  # long transaction or rewritten times, which only the application can
92
115
  # judge, so each move is reported rather than logged or refused.
93
- #: (untyped, String, TimeRange, Time?, Time?) -> TimeRange
94
- def self.moved_window(model_class, id, range, start, finish)
95
- window = moved(range, start, finish)
116
+ #: (untyped, String, TimeRange, TimeRange) -> void
117
+ def self.report_move(model_class, id, range, window)
96
118
  Instrumentation.notify(
97
119
  'moved_window',
98
120
  item_type: model_class.base_class.name, item_id: id,
99
121
  requested: range.to_range, window: window.to_range
100
122
  )
101
- window
102
123
  end
103
- private_class_method :moved_window
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))
140
+ end
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
104
149
 
105
150
  #: (untyped) -> untyped
106
151
  def self.transaction_versions(model_class)
107
- return unless model_class.paper_trail.version_class.column_names.include?('transaction_id')
108
-
109
- VersionQuery.for_model(model_class)
152
+ VersionQuery.for_model(model_class) if transactional?(model_class.paper_trail.version_class)
110
153
  end
111
154
  private_class_method :transaction_versions
112
155
 
113
- # Each root's earliest start among its transactions that cross the edge.
114
- #: (untyped, Array[untyped], Edge) -> Hash[String, Time]
115
- def self.moved_edges(versions, records, edge)
116
- 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)
117
168
  moved = {} #: Hash[String, Time]
118
- starts = crossing_starts(versions.klass, roots.keys, edge)
119
- starts.each_with_object(moved) do |(transaction, start), edges|
120
- 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
121
173
  end
122
174
  end
123
175
  private_class_method :moved_edges
124
176
 
125
- # The roots whose versions next to the edge each transaction holds.
126
- #: (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]]]
127
193
  def self.nearest_roots(versions, records, edge)
128
- records.each_slice(SLICE).flat_map { |slice| nearest(versions, slice, edge) }
129
- .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)]
130
202
  end
131
203
  private_class_method :nearest_roots
132
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
+
133
212
  # Each root's nearest versions on either side of an edge, as [id,
134
- # transaction] pairs; versions tied at the nearest instant are all kept.
135
- # One statement per slice: a grouped pass over the roots' versions finds
136
- # both instants, and a join reads the versions saved at either. A lookup
137
- # per root, joined by UNION ALL, took SQL Server about a second per 200
138
- # roots to compile. Rows read without a model come back as the adapter
139
- # returns them, so the transaction is cast as the grouped query's keys are.
140
- #: (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]]
141
225
  def self.nearest(versions, records, edge)
142
226
  transaction = versions.type_for_attribute('transaction_id')
143
- versions.connection.select_rows(nearest_sql(versions, records, edge)).map do |id, value|
144
- [id.to_s, transaction.cast(value)]
145
- 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)] }
146
229
  end
147
230
  private_class_method :nearest
148
231
 
149
- # The roots' versions saved in a transaction at either nearest instant.
150
- #: (untyped, Array[untyped], Edge) -> String
151
- def self.nearest_sql(versions, records, edge)
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)
152
236
  own = versions.where(item_id: records)
237
+ table = own.arel_table
153
238
  instants = nearest_instants(own, edge)
154
- own.joins(arel::Nodes::InnerJoin.new(instants, at_either(own.arel_table, instants)))
155
- .where.not(transaction_id: nil).select(:item_id, :transaction_id).to_sql
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')
156
253
  end
157
- private_class_method :nearest_sql
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?
158
265
 
159
266
  # Each root's latest instant before the edge and earliest after it, from
160
267
  # every version, saved in a transaction or not.
@@ -162,8 +269,9 @@ module PaperTrailDiff
162
269
  def self.nearest_instants(own, edge)
163
270
  table = own.arel_table
164
271
  column = table[:created_at]
165
- before = side_instant(arel::Nodes::Max, edge.left(column), column).as('before_at')
166
- after = side_instant(arel::Nodes::Min, edge.right(column), column).as('after_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')
167
275
  own.group(:item_id).select(table[:item_id], before, after).arel.as('paper_trail_diff_nearest')
168
276
  end
169
277
  private_class_method :nearest_instants
@@ -171,7 +279,7 @@ module PaperTrailDiff
171
279
  # The latest or earliest of the times on one side of the edge.
172
280
  #: (untyped, untyped, untyped) -> untyped
173
281
  def self.side_instant(aggregate, side, column)
174
- aggregate.new([arel::Nodes::Case.new.when(side).then(column)])
282
+ aggregate.new([Support.arel::Nodes::Case.new.when(side).then(column)])
175
283
  end
176
284
  private_class_method :side_instant
177
285
 
@@ -180,52 +288,45 @@ module PaperTrailDiff
180
288
  def self.at_either(table, instants)
181
289
  column = table[:created_at]
182
290
  at_either = column.eq(instants[:before_at]).or(column.eq(instants[:after_at]))
183
- arel::Nodes::On.new(table[:item_id].eq(instants[:item_id]).and(at_either))
291
+ Support.arel::Nodes::On.new(table[:item_id].eq(instants[:item_id]).and(at_either))
184
292
  end
185
293
  private_class_method :at_either
186
294
 
187
- # Where each transaction that has versions on both sides of the edge began.
188
- #: (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
189
- def self.crossing_starts(version_class, transactions, edge)
190
- earlier = edge.left(version_class.arel_table[:created_at])
191
- later = later_version(version_class.arel_table, edge)
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])
192
301
  starts = {} #: Hash[untyped, Time]
193
- transactions.each_slice(SLICE).with_object(starts) do |slice, found|
194
- crossing = version_class.where(transaction_id: slice).where(earlier).where(later)
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
195
307
  found.merge!(crossing.group(:transaction_id).minimum(:created_at))
196
308
  end
197
309
  end
198
310
  private_class_method :crossing_starts
199
311
 
200
- # Another version of the same transaction on the edge's later side.
201
- #: (untyped, Edge) -> untyped
202
- def self.later_version(table, edge)
203
- other = other_versions(table)
204
- arel::SelectManager.new.from(other).project('1')
205
- .where(other[:transaction_id].eq(table[:transaction_id])
206
- .and(edge.right(other[:created_at])))
207
- .exists
208
- end
209
- private_class_method :later_version
210
-
211
- # The version table under a second name, for a subquery over it. Any name
212
- # serves, and SQLite even accepts an empty one other databases refuse, so
213
- # no spec can tell the mutations apart.
214
- # mutant:disable
215
- #: (untyped) -> untyped
216
- def self.other_versions(table)
217
- table.alias('paper_trail_diff_crossing_versions')
218
- end
219
- private_class_method :other_versions
220
-
221
- # Arel ships no signatures; see VersionQuery. Any spelling of the constant
222
- # finds the same module.
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.
223
322
  # mutant:disable
224
- #: () -> untyped
225
- def self.arel
226
- Object.const_get(:Arel)
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)
227
328
  end
228
- private_class_method :arel
329
+ private_class_method :saved_later
229
330
 
230
331
  #: (TimeRange, Time?, Time?) -> TimeRange
231
332
  def self.moved(range, start, finish)
@@ -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.16.0'
5
+ VERSION = '0.17.1'
6
6
  end
@@ -24,28 +24,26 @@ 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
 
32
+ # A version saved before the start names the state there unless a later
33
+ # one saved before the start replaced it. PT-AT stores the keys a version
34
+ # saved, and a start inside a transaction reads each record as it stood
35
+ # before the transaction, so a later version that the record's
36
+ # transaction across the start saved before it replaced nothing yet.
37
+ # Without the version before it, a record that this transaction moved
38
+ # away is not found, nor is the transaction (see
39
+ # PreparedHistoryLoader#reload).
43
40
  #: (untyped) -> String
44
41
  def condition_sql(connection) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
45
42
  outer = connection.quote_table_name(@version_class.table_name)
46
43
  later = connection.quote_table_name('paper_trail_diff_later_versions')
44
+ crossing = connection.quote_table_name('paper_trail_diff_crossing_versions')
47
45
  start_at = quote_time(connection, @start_at)
48
- columns = quoted_columns(connection, outer, later)
46
+ columns = quoted_columns(connection, outer, later, crossing)
49
47
  compact_sql(<<~SQL)
50
48
  (
51
49
  #{activity_condition(columns, start_at, connection)}
@@ -59,14 +57,22 @@ module PaperTrailDiff
59
57
  AND #{columns.fetch(:later_item_id)} = #{columns.fetch(:outer_item_id)}
60
58
  AND #{columns.fetch(:later_created_at)} < #{start_at}
61
59
  AND #{columns.fetch(:later_created_at)} > #{columns.fetch(:outer_created_at)}
60
+ AND NOT EXISTS (
61
+ SELECT 1
62
+ FROM #{outer} #{crossing}
63
+ WHERE #{columns.fetch(:crossing_item_type)} = #{columns.fetch(:later_item_type)}
64
+ AND #{columns.fetch(:crossing_item_id)} = #{columns.fetch(:later_item_id)}
65
+ AND #{columns.fetch(:crossing_transaction_id)} = #{columns.fetch(:later_transaction_id)}
66
+ AND #{columns.fetch(:crossing_created_at)} >= #{start_at}
67
+ )
62
68
  )
63
69
  )
64
70
  )
65
71
  SQL
66
72
  end
67
73
 
68
- #: (untyped, String, String) -> Hash[Symbol, String]
69
- def quoted_columns(connection, outer, later)
74
+ #: (untyped, String, String, String) -> Hash[Symbol, String]
75
+ def quoted_columns(connection, outer, later, crossing)
70
76
  {
71
77
  outer_created_at: column(connection, outer, 'created_at'),
72
78
  outer_event: column(connection, outer, 'event'),
@@ -74,7 +80,12 @@ module PaperTrailDiff
74
80
  outer_item_id: column(connection, outer, 'item_id'),
75
81
  later_created_at: column(connection, later, 'created_at'),
76
82
  later_item_type: column(connection, later, 'item_type'),
77
- later_item_id: column(connection, later, 'item_id')
83
+ later_item_id: column(connection, later, 'item_id'),
84
+ later_transaction_id: column(connection, later, 'transaction_id'),
85
+ crossing_created_at: column(connection, crossing, 'created_at'),
86
+ crossing_item_type: column(connection, crossing, 'item_type'),
87
+ crossing_item_id: column(connection, crossing, 'item_id'),
88
+ crossing_transaction_id: column(connection, crossing, 'transaction_id')
78
89
  }
79
90
  end
80
91