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
@@ -41,10 +41,23 @@ module PaperTrailDiff
41
41
  # without destroy history has no rows and is left out.
42
42
  #: () -> Hash[Array[String], Array[ChangeRow]]
43
43
  def change_rows
44
- rows = {} #: Hash[Array[String], Array[ChangeRow]]
45
- analyses.each { |identity, analysis| rows[identity] = analysis.change_rows }
46
- deleted.each { |identity, analysis| rows[identity] = analysis.change_rows if analysis }
47
- rows.freeze
44
+ each_root(&:change_rows)
45
+ end
46
+
47
+ # The analysis of one of `roots`, found from the record itself. The keys
48
+ # are its base class's name and its ID as a string, which a subclass or an
49
+ # integer ID gets wrong when built by hand. Raises KeyError for a record
50
+ # the selection did not load; a deleted root's analysis is in `deleted`.
51
+ #: (untyped) -> Analysis
52
+ def analysis_for(record)
53
+ analyses.fetch(Endpoint.identity(record))
54
+ end
55
+
56
+ # Each root's net changes, keyed as `change_rows` is; the block picks the
57
+ # rows to keep, as for Analysis#net_changes.
58
+ #: () ?{ (ChangeRow) -> boolish } -> Hash[Array[String], Array[NetChange]]
59
+ def net_changes(&keep)
60
+ each_root { |analysis| analysis.net_changes(&keep) }
48
61
  end
49
62
 
50
63
  # Two elements, not three: `roots` is reached by name so that existing
@@ -53,5 +66,15 @@ module PaperTrailDiff
53
66
  def to_ary
54
67
  [analyses, unreachable]
55
68
  end
69
+
70
+ private
71
+
72
+ # What the block makes of each root's analysis: the roots that still
73
+ # exist, then the deleted ones that have history to report.
74
+ #: [T] () { (Analysis) -> T } -> Hash[Array[String], T]
75
+ def each_root(&block)
76
+ reported = deleted.filter_map { |identity, analysis| [identity, analysis] if analysis }
77
+ analyses.merge(reported.to_h).transform_values(&block).freeze
78
+ end
56
79
  end
57
80
  end
@@ -4,10 +4,10 @@
4
4
  module PaperTrailDiff
5
5
  # Selects both populations and checks their shared ceiling before analysis.
6
6
  class ScopedAnalysisBuilder
7
- #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
7
+ #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
9
  scope, limit:, within:, historical_filter:, max_filter_versions:, include_deleted:,
10
- analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: nil
10
+ analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: nil, traversal: nil
11
11
  )
12
12
  raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
13
13
  unless [true, false].include?(include_deleted)
@@ -17,7 +17,8 @@ module PaperTrailDiff
17
17
  @selection = ScopedRootSelection.new(
18
18
  scope, limit: limit, time_range: within.nil? ? nil : TimeRange.new(within),
19
19
  historical_filter: historical_filter, max_filter_versions: max_filter_versions,
20
- activity_tree: activity_tree, version_scope: version_scope
20
+ activity_tree: activity_tree, version_scope: version_scope,
21
+ traversal: traversal
21
22
  )
22
23
  @deleted_filter = deleted_filter(scope, include_deleted)
23
24
  @include_deleted = include_deleted
@@ -26,8 +26,9 @@ module PaperTrailDiff
26
26
  # window. `where(status: 'published')` selects what is published now, which is
27
27
  # not the same set as what was published while the window was open.
28
28
  class ScopedRootSelection
29
- PAGE_SIZE = 250
30
- private_constant :PAGE_SIZE
29
+ MIN_PAGE_SIZE = 250
30
+ MAX_PAGE_SIZE = 2_000
31
+ private_constant :MIN_PAGE_SIZE, :MAX_PAGE_SIZE
31
32
 
32
33
  # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
33
34
  # gem supports 3.1.
@@ -45,26 +46,23 @@ module PaperTrailDiff
45
46
 
46
47
  # `activity_tree` names the association paths whose changes also select a
47
48
  # root, as an activity analysis reports them. Without one, only a root's
48
- # own versions select it. `version_scope` narrows which of those count,
49
- # as it narrows which are reported.
50
- #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
49
+ # own versions select it. `version_scope` narrows which of either count,
50
+ # as it narrows which are reported. `traversal` names the requested paths,
51
+ # which decide where a window's edges move (see TransactionCut).
52
+ #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
51
53
  def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
52
54
  max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil,
53
- version_scope: nil)
55
+ version_scope: nil, traversal: nil)
54
56
  @scope = normalize_scope(scope)
55
57
  reject_unversioned!
56
58
  @time_range = time_range
59
+ @path_types = traversal ? traversal.path_types(model) : [] #: Array[String]
57
60
  @version_scope = VersionScopeFilter.validated(version_scope)
58
61
  @limit = validate_limit(limit)
59
- @related = if activity_tree
60
- AssociationActivitySelection.new(model, tree: activity_tree,
61
- time_range: time_range)
62
- end
63
- @historical_filter = unless historical_filter.nil?
64
- HistoricalFilter.new(base_class, predicate: historical_filter,
65
- time_range: time_range, limit: @limit,
66
- max_versions: max_filter_versions)
67
- end
62
+ @related = activity_tree && AssociationActivitySelection.new(
63
+ model, tree: activity_tree, time_range: time_range, version_scope: @version_scope
64
+ )
65
+ @historical_filter = historical_filter_for(historical_filter, max_filter_versions, traversal)
68
66
  end
69
67
 
70
68
  #: () -> Result
@@ -84,6 +82,7 @@ module PaperTrailDiff
84
82
  # @rbs @historical_filter: untyped
85
83
  # @rbs @related: AssociationActivitySelection?
86
84
  # @rbs @version_scope: untyped
85
+ # @rbs @path_types: Array[String]
87
86
 
88
87
  # Leaves the candidate set in the database. Plucking every root changed in
89
88
  # the window would cost memory and a statement proportional to all activity
@@ -121,13 +120,22 @@ module PaperTrailDiff
121
120
  live = ids_in(base_class.unscoped, candidates)
122
121
  missing = candidates - live
123
122
  if (filter = @historical_filter)
124
- live = filter.call(ids_in(@scope.except(:order, :limit, :offset), live).uniq)
123
+ live = filter.call(relation_members(live))
125
124
  missing = filter.call(missing, counted: false)
126
125
  end
127
126
  Result.new(records: selected_records([live]),
128
127
  unreachable: missing.sort.map { |id| identity(id) }.freeze)
129
128
  end
130
129
 
130
+ # The candidates the relation's conditions accept. A grouped relation's
131
+ # rows are groups, which a condition on one record cannot decide, and its
132
+ # aggregates read every candidate at once, so it keeps them all: the
133
+ # filter reads each, and the relation groups those that match.
134
+ #: (Array[String]) -> Array[String]
135
+ def relation_members(ids)
136
+ @scope.group_values.empty? ? ids_in(@scope.except(:order, :limit, :offset), ids).uniq : ids
137
+ end
138
+
131
139
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
132
140
  # rejects an integer key against a string item_id outright. A composite
133
141
  # key names no single attribute, so it has no type and never matches.
@@ -155,15 +163,25 @@ module PaperTrailDiff
155
163
  end
156
164
 
157
165
  # Only the versions `version_scope` keeps select a root: one whose versions
158
- # in the window it drops would have nothing to report.
166
+ # in the window it drops would have nothing to report. A version saved
167
+ # just before the window selects its root when TransactionCut moves the
168
+ # root's window back to take it in.
159
169
  #: () -> untyped
160
170
  def window_versions
161
- relation = VersionQuery.for_model(model)
162
- range = @time_range
163
- relation = range.scope(relation) if range
171
+ relation = TransactionCut.window_versions(model, @time_range, @path_types)
164
172
  @version_scope ? @version_scope.call(relation) : relation
165
173
  end
166
174
 
175
+ # The filter reads each candidate over the window its analysis will.
176
+ #: (untyped, Integer, AssociationTraversal?) -> HistoricalFilter?
177
+ def historical_filter_for(predicate, max_versions, traversal)
178
+ return if predicate.nil?
179
+
180
+ HistoricalFilter.new(base_class, predicate: predicate, time_range: @time_range,
181
+ limit: @limit, max_versions: max_versions,
182
+ windows: TransactionCut.reader(model, traversal))
183
+ end
184
+
167
185
  # Accepts a model class as readily as a relation: `Article` and
168
186
  # `Article.where(...)` both name a population, and `all` is what makes them
169
187
  # the same kind of thing.
@@ -202,7 +220,7 @@ module PaperTrailDiff
202
220
 
203
221
  #: (untyped, Array[String]) -> Array[String]
204
222
  def ids_in(relation, candidates)
205
- candidates.each_slice(PAGE_SIZE).flat_map do |slice|
223
+ candidates.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
206
224
  relation.where(primary_key => slice).pluck(primary_key).map(&:to_s)
207
225
  end
208
226
  end
@@ -221,18 +239,19 @@ module PaperTrailDiff
221
239
  page = record_page(relation, consumed)
222
240
  page.each { |record| records[record.id] ||= record }
223
241
  reject_oversized!(records.length)
224
- break if page.length < PAGE_SIZE
242
+ break if page.length < page_size
225
243
 
226
244
  consumed += page.length
227
245
  end
228
246
  records.values.freeze
229
247
  end
230
248
 
249
+ # Pages are read by offset, so under a total order.
231
250
  #: (Array[untyped]) -> untyped
232
251
  def candidate_relation(candidates)
233
252
  candidates.map do |ids|
234
253
  conditions = { primary_key => ids } #: Hash[untyped, untyped]
235
- ordered_scope.where(conditions)
254
+ TotalOrder.apply(@scope).where(conditions)
236
255
  end.reduce(:or)
237
256
  end
238
257
 
@@ -241,22 +260,26 @@ module PaperTrailDiff
241
260
  count = page_limit(consumed)
242
261
  return [] if count.zero?
243
262
 
244
- relation.offset((@scope.offset_value || 0) + consumed).limit(count)
245
- end
246
-
247
- # Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
248
- # even when the extra ordering would only have served as a tie-breaker.
249
- #: () -> untyped
250
- def ordered_scope
251
- return @scope unless @scope.order_values.empty?
252
-
253
- @scope.order(primary_key => :asc)
263
+ relation.offset(Support.offset(@scope) + consumed).limit(count)
254
264
  end
255
265
 
256
266
  #: (Integer) -> Integer
257
267
  def page_limit(consumed)
258
- remaining = @scope.limit_value
259
- [remaining ? remaining - consumed : PAGE_SIZE, PAGE_SIZE].min
268
+ remaining = Support.limit(@scope)
269
+ [remaining ? remaining - consumed : page_size, page_size].min
270
+ end
271
+
272
+ # Every page repeats the candidates, a list of ids or the subqueries that
273
+ # find them, and skips the rows read before it, so pages much smaller than
274
+ # the selection read the candidates many times over. More roots than
275
+ # `limit:` raise, so a page never needs more than one past it. A page
276
+ # holds at least 250 rows, for a relation whose joins repeat a record,
277
+ # and at most 2,000: SQL Server compiles a statement with its ids written
278
+ # in, and one that listed 20,000 and returned them all outlasted the
279
+ # adapter's default timeout of 5 seconds.
280
+ #: () -> Integer
281
+ def page_size
282
+ (@limit + 1).clamp(MIN_PAGE_SIZE, MAX_PAGE_SIZE)
260
283
  end
261
284
 
262
285
  #: (Integer) -> void
@@ -268,14 +291,10 @@ module PaperTrailDiff
268
291
  'relation, or raise limit: to the page size you intend to analyze'
269
292
  end
270
293
 
294
+ # Keyed as Endpoint.identity keys the record, which the analyses use.
271
295
  #: (String) -> Array[String]
272
296
  def identity(id)
273
- [item_type, id].freeze
274
- end
275
-
276
- #: () -> String
277
- def item_type
278
- base_class.name
297
+ Support.record_identity(model, id).freeze
279
298
  end
280
299
 
281
300
  # A relation delegates class methods to its model, so every mutation here,
@@ -56,6 +56,7 @@ module PaperTrailDiff
56
56
  @pool = pool
57
57
  @structural_columns = {} #: Hash[String, Array[String]]
58
58
  @excluded_attributes = {} #: Hash[Array[untyped], Array[String?]]
59
+ @leaves = {} #: Hash[String, Hash[PreparedRecordState, RecordSnapshot]]
59
60
  end
60
61
 
61
62
  #: (untyped, reifier: untyped) -> RecordSnapshot?
@@ -90,8 +91,22 @@ module PaperTrailDiff
90
91
  end
91
92
 
92
93
  # Same exclusions as AR normalization, applied to an already typed state.
94
+ # A state without associations is normalized once at each path: the
95
+ # same state is read again at every boundary it spans.
93
96
  #: (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
94
97
  def from_state(state, tree:, path:, incoming: nil, associations: {})
98
+ unless associations.empty?
99
+ return snapshot_from_state(state, tree, path, incoming, associations)
100
+ end
101
+
102
+ leaves = @leaves[path] ||= {}
103
+ leaves[state] ||= snapshot_from_state(state, tree, path, incoming, associations)
104
+ end
105
+
106
+ private
107
+
108
+ #: (PreparedRecordState, AssociationTree, String, untyped, snapshot_associations) -> RecordSnapshot
109
+ def snapshot_from_state(state, tree, path, incoming, associations)
95
110
  model = state.model_class
96
111
  @structural_columns[path] ||= @traversal.incoming_relationship_columns(incoming) if incoming
97
112
  reflections = @traversal.reflections_for(model, tree, path: path)
@@ -104,8 +119,6 @@ module PaperTrailDiff
104
119
  pool_state(path, snapshot)
105
120
  end
106
121
 
107
- private
108
-
109
122
  # The id a live record of the same row reports: one value, or one per
110
123
  # column of a composite key.
111
124
  #: (untyped, PreparedRecordState) -> untyped
@@ -125,6 +138,7 @@ module PaperTrailDiff
125
138
  # @rbs @pool: SnapshotPool
126
139
  # @rbs @structural_columns: Hash[String, Array[String]]
127
140
  # @rbs @excluded_attributes: Hash[Array[untyped], Array[String?]]
141
+ # @rbs @leaves: Hash[String, Hash[PreparedRecordState, RecordSnapshot]]
128
142
 
129
143
  #: (untyped, AssociationTree, String, untyped, Array[untyped]) -> RecordSnapshot
130
144
  def normalize_record(record, tree, path, reifier, reflections)
@@ -141,7 +155,7 @@ module PaperTrailDiff
141
155
  def normalized_attributes(record, reflections, path)
142
156
  attributes = record.attributes
143
157
  excluded_attributes(record, reflections, path).each { |name| attributes.delete(name) }
144
- StoredTimePrecision.apply(attributes, StoredTimePrecision.digits(record.class))
158
+ StoredValues.apply(record.class, attributes)
145
159
  end
146
160
 
147
161
  # Every input is fixed for one model class at one selected path, and the
@@ -222,6 +236,7 @@ module PaperTrailDiff
222
236
  def normalize_children(records, tree, path, reifier)
223
237
  reflections_by_class = {} #: Hash[untyped, Array[untyped]]
224
238
  records.map do |child|
239
+ Support.with_recorded_times(child)
225
240
  reflections = reflections_by_class[child.class] ||= reflections_for(child, tree, path)
226
241
  reifier.reify(child, reflections) unless reflections.empty?
227
242
  normalize_record(child, tree, path, reifier, reflections)
@@ -0,0 +1,52 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Reads values in the form JSON history gives them back.
6
+ #
7
+ # A `json` or `jsonb` object column stores a record's attributes as they
8
+ # are, without PaperTrail's attribute serializer, so a `serialize`d value
9
+ # comes back as JSON writes it: keys as strings, and dates, times and
10
+ # symbols inside it as strings, which its type does not cast back.
11
+ # PaperTrail's JSON serializer stores a binary value as `{"value" => bytes}`,
12
+ # which its type does not cast back either. Compared as they are, the live
13
+ # row and every version would differ though nothing was edited. So every
14
+ # side is read in one form: a `serialize`d value as JSON writes it, and a
15
+ # binary value as its bytes. Both leave a value read from history as it is.
16
+ module StoredJsonValues
17
+ SERIALIZED_TYPE = 'ActiveRecord::Type::Serialized'
18
+ BINARY_TYPE = 'ActiveModel::Type::Binary'
19
+ BINARY_KEYS = ['value'].freeze
20
+ private_constant :SERIALIZED_TYPE, :BINARY_TYPE, :BINARY_KEYS
21
+
22
+ # For a model whose history is JSON, which StoredTimePrecision.digits
23
+ # tells: a `json` or `jsonb` object column, or the JSON serializer.
24
+ #: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
25
+ def self.apply(model_class, attributes)
26
+ if StoredTimePrecision.json_column?(model_class.paper_trail.version_class, 'object')
27
+ convert(model_class, attributes, SERIALIZED_TYPE, &:as_json)
28
+ else
29
+ convert(model_class, attributes, BINARY_TYPE) { |value| bytes(value) }
30
+ end
31
+ end
32
+
33
+ # The attributes with the value of each of this type converted. An
34
+ # adapter's type can be a subclass, as PostgreSQL's `bytea` is of binary.
35
+ #: (untyped, Hash[untyped, untyped], String) { (untyped) -> untyped } -> Hash[untyped, untyped]
36
+ def self.convert(model_class, attributes, type_name)
37
+ type = Support.constant(type_name)
38
+ attributes.to_h do |name, value|
39
+ [name, model_class.type_for_attribute(name).is_a?(type) ? yield(value) : value]
40
+ end
41
+ end
42
+ private_class_method :convert
43
+
44
+ #: (untyped) -> untyped
45
+ def self.bytes(value)
46
+ return value unless value.instance_of?(Hash) && value.keys == BINARY_KEYS
47
+
48
+ value.fetch('value').b
49
+ end
50
+ private_class_method :bytes
51
+ end
52
+ end
@@ -17,52 +17,64 @@ module PaperTrailDiff
17
17
  JSON_COLUMN_TYPES = %i[json jsonb].freeze
18
18
  private_constant :NANOSECOND_DIGITS, :JSON_COLUMN_TYPES
19
19
 
20
- module_function
21
-
22
20
  # Fractional digits a model's history keeps for times, or nil when the
23
21
  # history is stored losslessly.
24
22
  #: (untyped) -> Integer?
25
- def digits(model_class)
23
+ def self.digits(model_class)
26
24
  return unless Support.versioned?(model_class)
27
25
  return unless json_history?(model_class.paper_trail.version_class)
28
26
 
29
- active_support = Object.const_get(:ActiveSupport) #: untyped
30
- active_support.const_get(:JSON).const_get(:Encoding).time_precision
27
+ json_time_precision
31
28
  end
32
29
 
33
30
  #: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
34
- def apply(attributes, digits)
31
+ def self.apply(attributes, digits)
35
32
  return attributes unless digits
36
33
 
37
34
  attributes.transform_values { |value| truncate(value, digits) }
38
35
  end
39
36
 
37
+ # From nine digits on, the step is one nanosecond or a fraction of one, so
38
+ # nothing is cut.
40
39
  #: (untyped, Integer) -> untyped
41
- def truncate(value, digits)
42
- return value unless value.is_a?(Time) && digits < NANOSECOND_DIGITS
40
+ def self.truncate(value, digits)
41
+ return value unless value.is_a?(Time)
43
42
 
44
43
  # ActiveSupport's Time#change, which also serves TimeWithZone.
45
44
  time = value #: untyped
46
- step = 10**(NANOSECOND_DIGITS - [digits, 0].max) #: Integer
47
- remainder = time.nsec % step
45
+ remainder = time.nsec % (10**(NANOSECOND_DIGITS - digits))
48
46
  remainder.zero? ? time : time.change(nsec: time.nsec - remainder)
49
47
  end
50
48
 
51
49
  #: (untyped) -> bool
52
- def json_history?(version_class)
53
- columns = version_class.columns_hash
54
- json_column = %w[object object_changes].any? do |name|
55
- JSON_COLUMN_TYPES.include?(columns[name]&.type)
56
- end
57
- json_column || json_serializer?
50
+ def self.json_history?(version_class)
51
+ %w[object object_changes].any? { |name| json_column?(version_class, name) } ||
52
+ json_serializer?
58
53
  end
59
54
  private_class_method :json_history?
60
55
 
56
+ # Whether the version table keeps this column as `json` or `jsonb`, which
57
+ # PaperTrail writes without its serializer.
58
+ #: (untyped, String) -> bool
59
+ def self.json_column?(version_class, name)
60
+ JSON_COLUMN_TYPES.include?(version_class.columns_hash[name]&.type)
61
+ end
62
+
63
+ # mutant:disable - Every mutation that survives here reads the same
64
+ # constant another way: from this module rather than Object, or with `::`.
65
+ #: () -> Integer
66
+ def self.json_time_precision
67
+ active_support = Object.const_get(:ActiveSupport) #: untyped
68
+ active_support.const_get(:JSON).const_get(:Encoding).time_precision
69
+ end
70
+ private_class_method :json_time_precision
71
+
72
+ # Whether PaperTrail writes history with its JSON serializer.
73
+ # mutant:disable - As for json_time_precision.
61
74
  #: () -> bool
62
- def json_serializer?
75
+ def self.json_serializer?
63
76
  paper_trail = Object.const_get(:PaperTrail) #: untyped
64
77
  paper_trail.serializer.equal?(paper_trail.const_get(:Serializers).const_get(:JSON))
65
78
  end
66
- private_class_method :json_serializer?
67
79
  end
68
80
  end
@@ -0,0 +1,20 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Reads a model's attribute values in the one form every account of them
6
+ # shares: a version decoded from history, the current row, and the changes
7
+ # a version recorded. Each would otherwise differ where nothing was edited.
8
+ # TimeOfDay puts a time of day on one date, and for JSON history,
9
+ # StoredJsonValues and StoredTimePrecision read values as JSON stored them.
10
+ module StoredValues
11
+ #: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
12
+ def self.apply(model_class, attributes)
13
+ attributes = TimeOfDay.apply(model_class, attributes)
14
+ digits = StoredTimePrecision.digits(model_class)
15
+ return attributes unless digits
16
+
17
+ StoredTimePrecision.apply(StoredJsonValues.apply(model_class, attributes), digits)
18
+ end
19
+ end
20
+ end