paper_trail_diff 0.17.1 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +648 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +15 -23
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +214 -182
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +12 -10
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +9 -16
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +138 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +11 -5
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
@@ -35,34 +35,39 @@ module PaperTrailDiff
35
35
  class Result
36
36
  attr_reader :records #: Array[untyped]
37
37
  attr_reader :unreachable #: Array[Array[String]]
38
+ # How many records the relation selects before its limit and offset.
39
+ attr_reader :total #: Integer
38
40
 
39
- #: (records: Array[untyped], unreachable: Array[Array[String]]) -> void
40
- def initialize(records:, unreachable:)
41
+ #: (records: Array[untyped], unreachable: Array[Array[String]], total: Integer) -> void
42
+ def initialize(records:, unreachable:, total:)
41
43
  @records = records
42
44
  @unreachable = unreachable
45
+ @total = total
43
46
  freeze
44
47
  end
45
48
  end
46
49
 
47
- # `activity_tree` names the association paths whose changes also select a
50
+ # `activity_traversal` names the association paths whose changes also select a
48
51
  # root, as an activity analysis reports them. Without one, only a root's
49
52
  # 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
53
- def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
54
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil,
55
- version_scope: nil, traversal: nil)
53
+ # as it narrows which are reported.
54
+ #
55
+ # A window selects by the versions saved in it. A transaction that saves
56
+ # there and ends after it is reported in a later window (see
57
+ # TransactionEnds), so a root can be selected with nothing to report. One
58
+ # open at the window's start is reported in it, though it may have saved
59
+ # the root's tree only before it, so with associations the roots are
60
+ # selected from where the earliest such transaction began.
61
+ #: (untyped, time_range: TimeRange?, limit: Integer, ?activity_traversal: AssociationTraversal?, ?version_scope: untyped) -> void
62
+ def initialize(scope, time_range:, limit:, activity_traversal: nil, version_scope: nil)
56
63
  @scope = normalize_scope(scope)
57
64
  reject_unversioned!
58
- @time_range = time_range
59
- @path_types = traversal ? traversal.path_types(model) : [] #: Array[String]
60
- @version_scope = VersionScopeFilter.validated(version_scope)
65
+ @version_scope = version_scope
61
66
  @limit = validate_limit(limit)
62
- @related = activity_tree && AssociationActivitySelection.new(
63
- model, tree: activity_tree, time_range: time_range, version_scope: @version_scope
67
+ @selecting = AssociationActivitySelection.window(model, activity_traversal, time_range)
68
+ @related = activity_traversal && AssociationActivitySelection.new(
69
+ model, traversal: activity_traversal, time_range: @selecting, version_scope: @version_scope
64
70
  )
65
- @historical_filter = historical_filter_for(historical_filter, max_filter_versions, traversal)
66
71
  end
67
72
 
68
73
  #: () -> Result
@@ -77,12 +82,10 @@ module PaperTrailDiff
77
82
  private
78
83
 
79
84
  # @rbs @scope: untyped
80
- # @rbs @time_range: TimeRange?
85
+ # @rbs @selecting: TimeRange?
81
86
  # @rbs @limit: Integer
82
- # @rbs @historical_filter: untyped
83
87
  # @rbs @related: AssociationActivitySelection?
84
88
  # @rbs @version_scope: untyped
85
- # @rbs @path_types: Array[String]
86
89
 
87
90
  # Leaves the candidate set in the database. Plucking every root changed in
88
91
  # the window would cost memory and a statement proportional to all activity
@@ -91,18 +94,29 @@ module PaperTrailDiff
91
94
  # bounded by what the relation and the deletions actually contain.
92
95
  #: (Array[AssociationActivitySelection::Query]) -> Result
93
96
  def database_selection(related)
94
- candidates = [window_versions.select(:item_id)] + related.map(&:relation)
95
- missing = (missing_ids + related_missing_ids(related)).uniq.sort
96
- Result.new(
97
- records: selected_records(candidates),
98
- unreachable: missing.map { |id| identity(id) }.freeze
99
- )
97
+ sources = [changed_roots, *related]
98
+ missing = Support.sort_ids(sources.flat_map { |ids| ids.missing(base_class) })
99
+ records, total = CandidateTable.union(base_class, sources.map(&:relation)) do |relations|
100
+ page_and_total(relations)
101
+ end
102
+ Result.new(records: records, unreachable: missing.map { |id| identity(id) }.freeze,
103
+ total: total)
104
+ end
105
+
106
+ # The roots with a version of their own in the window. Those without a
107
+ # row are found in the database too (see Query#missing), not by comparing
108
+ # two plucked lists. Only the related queries' types are compared, so
109
+ # this one names none.
110
+ #: () -> AssociationActivitySelection::Query
111
+ def changed_roots
112
+ AssociationActivitySelection::Query.new(window_versions, version_class.arel_table[:item_id],
113
+ nil)
100
114
  end
101
115
 
102
116
  # Comparing in SQL needs every subquery's column to share the key's type.
103
117
  #: (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
104
118
  def subqueries(related)
105
- return unless @historical_filter.nil? && comparable_keys?
119
+ return unless comparable_keys?
106
120
 
107
121
  queries = related.grep(AssociationActivitySelection::Query) #: Array[AssociationActivitySelection::Query]
108
122
  matching = queries.select { |ids| ids.type == key_type }
@@ -111,29 +125,14 @@ module PaperTrailDiff
111
125
 
112
126
  # Which candidates still have a row is asked without the relation's
113
127
  # conditions, so that "filtered out" and "no longer exists" stay
114
- # separable. A filter then reads the history of the relation's records
115
- # only, whose order and page choose among those that match, and of the
116
- # deleted ones, which no relation can test. Those it lists, as without a
117
- # filter, but does not count toward `limit:`.
128
+ # separable.
118
129
  #: (Array[String]) -> Result
119
130
  def plucked_selection(candidates)
120
131
  live = ids_in(base_class.unscoped, candidates)
121
132
  missing = candidates - live
122
- if (filter = @historical_filter)
123
- live = filter.call(relation_members(live))
124
- missing = filter.call(missing, counted: false)
125
- end
126
- Result.new(records: selected_records([live]),
127
- unreachable: missing.sort.map { |id| identity(id) }.freeze)
128
- end
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
133
+ records, total = CandidateTable.with(base_class, live) { |ids| page_and_total([ids]) }
134
+ unreachable = Support.sort_ids(missing).map { |id| identity(id) }.freeze
135
+ Result.new(records: records, unreachable: unreachable, total: total)
137
136
  end
138
137
 
139
138
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
@@ -149,37 +148,19 @@ module PaperTrailDiff
149
148
  base_class.type_for_attribute(primary_key).type
150
149
  end
151
150
 
152
- #: (Array[AssociationActivitySelection::Query]) -> Array[String]
153
- def related_missing_ids(related)
154
- live = base_class.unscoped.select(primary_key).arel
155
- related.flat_map { |ids| ids.missing(live) }.map(&:to_s)
156
- end
157
-
158
- # Changed in the window but without a row, found with an anti-join instead
159
- # of comparing two plucked lists.
160
- #: () -> Array[String]
161
- def missing_ids
162
- window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
163
- end
164
-
165
151
  # Only the versions `version_scope` keeps select a root: one whose versions
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.
152
+ # in the window it drops would have nothing to report. With associations
153
+ # it keeps whole transactions, as their activity reports them.
169
154
  #: () -> untyped
170
155
  def window_versions
171
- relation = TransactionCut.window_versions(model, @time_range, @path_types)
172
- @version_scope ? @version_scope.call(relation) : relation
173
- end
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))
156
+ range = @selecting
157
+ relation = VersionQuery.for_model(model)
158
+ relation = range.scope(relation) if range
159
+ scope = @version_scope
160
+ return relation unless scope
161
+ return scope.call(relation) unless @related
162
+
163
+ VersionScopeFilter.whole_transactions(scope, relation)
183
164
  end
184
165
 
185
166
  # Accepts a model class as readily as a relation: `Article` and
@@ -196,10 +177,7 @@ module PaperTrailDiff
196
177
 
197
178
  #: () -> void
198
179
  def reject_unversioned!
199
- return if Support.versioned?(model)
200
-
201
- raise UnversionedAssociationError,
202
- "scope: #{model} is not versioned, so it has no history to select from"
180
+ ReadableHistory.check_model!(model)
203
181
  end
204
182
 
205
183
  # No Integer subclass has instances, so this is `is_a?` by another name.
@@ -225,18 +203,33 @@ module PaperTrailDiff
225
203
  end
226
204
  end
227
205
 
206
+ # The records, and how many the relation selects before its limit and
207
+ # offset. An unpaged relation has read them all already; a paged one is
208
+ # counted in one more statement, with each record once, and a relation
209
+ # grouped by another column by its groups, each of which reads a record.
210
+ #: (Array[untyped]) -> [Array[untyped], Integer]
211
+ def page_and_total(candidates)
212
+ records = selected_records(candidates)
213
+ paged = Support.limit(@scope) || Support.offset(@scope).positive?
214
+ return [records, records.length] unless paged
215
+
216
+ counted = candidate_relation(*candidates).unscope(:limit, :offset).distinct.count(primary_key)
217
+ [records, counted.instance_of?(Hash) ? counted.length : counted]
218
+ end
219
+
228
220
  # Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
229
221
  # relation may order by joined columns or select a PostgreSQL json column.
230
222
  # Read bounded pages until the relation ends or too many unique roots appear.
231
- # Each candidate source is an id list or a subquery; a record matching any
232
- # of them is selected.
223
+ # Each candidate source is an id list or a subquery, such as a
224
+ # CandidateTable's; a record matching any of them is selected.
233
225
  #: (Array[untyped]) -> Array[untyped]
234
226
  def selected_records(candidates)
235
- relation = candidate_relation(candidates)
227
+ relation = candidate_relation(*candidates)
236
228
  records = {} #: Hash[untyped, untyped]
237
229
  consumed = 0
238
230
  loop do
239
231
  page = record_page(relation, consumed)
232
+ reject_keyless!(page)
240
233
  page.each { |record| records[record.id] ||= record }
241
234
  reject_oversized!(records.length)
242
235
  break if page.length < page_size
@@ -246,9 +239,23 @@ module PaperTrailDiff
246
239
  records.values.freeze
247
240
  end
248
241
 
242
+ # A relation that selects columns without the primary key reads rows that
243
+ # name no record.
244
+ #: (Array[untyped]) -> void
245
+ def reject_keyless!(page)
246
+ return if page.none? { |record| keyless?(record.id) }
247
+
248
+ raise ConfigurationError, "scope: selects columns without #{primary_key}, so its rows name " \
249
+ 'no record; select it too'
250
+ end
251
+
252
+ # A composite key names a record only when every part of it is read.
253
+ #: (untyped) -> bool
254
+ def keyless?(id) = [id].flatten.include?(nil)
255
+
249
256
  # Pages are read by offset, so under a total order.
250
- #: (Array[untyped]) -> untyped
251
- def candidate_relation(candidates)
257
+ #: (*untyped) -> untyped
258
+ def candidate_relation(*candidates)
252
259
  candidates.map do |ids|
253
260
  conditions = { primary_key => ids } #: Hash[untyped, untyped]
254
261
  TotalOrder.apply(@scope).where(conditions)
@@ -276,7 +283,8 @@ module PaperTrailDiff
276
283
  # holds at least 250 rows, for a relation whose joins repeat a record,
277
284
  # and at most 2,000: SQL Server compiles a statement with its ids written
278
285
  # in, and one that listed 20,000 and returned them all outlasted the
279
- # adapter's default timeout of 5 seconds.
286
+ # adapter's default timeout of 5 seconds. There a long list is now read
287
+ # from a CandidateTable, but other databases still repeat it.
280
288
  #: () -> Integer
281
289
  def page_size
282
290
  (@limit + 1).clamp(MIN_PAGE_SIZE, MAX_PAGE_SIZE)
@@ -306,9 +314,7 @@ module PaperTrailDiff
306
314
  end
307
315
 
308
316
  #: () -> untyped
309
- def base_class
310
- model.base_class
311
- end
317
+ def base_class = model.base_class
312
318
 
313
319
  #: () -> untyped
314
320
  def primary_key
@@ -0,0 +1,31 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # A window that selects records by activity, widened to where the earliest
6
+ # transaction open at its start began, as its history is read (see
7
+ # AssociationTraversal#reach_before). Associations are followed over all of
8
+ # it, but before the start only the versions of the transactions open there
9
+ # select a record: the window reports those transactions, and none of the
10
+ # others, which ended before it.
11
+ class SelectionWindow < TimeRange
12
+ #: (TimeRange, untyped) -> void
13
+ def initialize(window, reach)
14
+ @window = window
15
+ super(window.widened(reach).to_range, digits: window.digits)
16
+ end
17
+
18
+ #: (untyped) -> untyped
19
+ def scope(relation)
20
+ in_window = @window.scope(relation)
21
+ version_class = relation.klass
22
+ return in_window unless version_class.column_names.include?('transaction_id')
23
+
24
+ crossing = CrossingTransactions.saved_before(version_class, @window.begin_time)
25
+ saved = { version_class.primary_key => crossing } #: Hash[untyped, untyped]
26
+ in_window.or(relation.where(saved))
27
+ end
28
+
29
+ # @rbs @window: TimeRange
30
+ end
31
+ end
@@ -38,63 +38,50 @@ module PaperTrailDiff
38
38
 
39
39
  # A normalized association in a bounded record snapshot tree.
40
40
  class AssociationSnapshot
41
- COLLECTION_KINDS = %i[has_many has_and_belongs_to_many].freeze
42
- SUPPORTED_KINDS = %i[belongs_to has_one has_many has_and_belongs_to_many].freeze
43
- private_constant :COLLECTION_KINDS, :SUPPORTED_KINDS
44
-
45
- # Non-semantic memoization shared by structurally adjacent snapshots. The
46
- # cached value is derived only from frozen records and is itself immutable.
47
- class IdentityIndexCache
41
+ # Whether a collection's identities were found distinct. The snapshots a
42
+ # transition derives from one another share the answer: a transition
43
+ # replaces a record in its place, takes one out, or puts in one that was
44
+ # not there, and none of those can repeat an identity. Records are held
45
+ # in identity order, so two with one identity are neighbours.
46
+ class IdentityCheck
48
47
  #: () -> void
49
48
  def initialize
50
- @index = nil #: CollectionIdentityIndex?
51
- end
52
-
53
- #: (Array[RecordSnapshot]) -> CollectionIdentityIndex
54
- def index(records)
55
- @index ||= CollectionIdentityIndex.new(records)
49
+ @passed = false
56
50
  end
57
- end
58
- private_constant :IdentityIndexCache
59
51
 
60
- # Identifies one snapshot for internal carry-forward. A transition cannot
61
- # hold its origin without retaining every earlier snapshot at that path,
62
- # and `object_id` is only guaranteed unique among live objects, so Ruby may
63
- # hand a collected snapshot's id to a later one.
64
- class SerialSequence
65
- #: () -> void
66
- def initialize
67
- @mutex = Mutex.new
68
- @counter = 0
69
- end
52
+ #: (Array[RecordSnapshot]) -> void
53
+ def call(records)
54
+ return if @passed
70
55
 
71
- #: () -> Integer
72
- def next_serial
73
- @mutex.synchronize { @counter += 1 }
56
+ records.map(&:identity).each_cons(2) do |left, right|
57
+ raise ArgumentError, "duplicate record identity: #{right}" if left.eql?(right)
58
+ end
59
+ @passed = true
74
60
  end
75
-
76
- # @rbs @mutex: Thread::Mutex
77
- # @rbs @counter: Integer
78
61
  end
79
- private_constant :SerialSequence
80
-
81
- SERIALS = SerialSequence.new
82
- private_constant :SERIALS
62
+ private_constant :IdentityCheck
83
63
 
84
64
  class << self
85
65
  #: (Symbol) -> bool
86
66
  def collection_kind?(kind)
87
- COLLECTION_KINDS.include?(kind)
67
+ kind == :has_many
88
68
  end
89
69
  end
90
70
 
91
71
  attr_reader :kind #: Symbol
92
72
  attr_reader :records #: Array[RecordSnapshot]
93
- attr_reader :serial #: Integer
94
-
95
- #: (kind: Symbol, records: Array[RecordSnapshot], ?identity_index_cache: untyped, ?transition: CollectionTransition?) -> void
96
- def initialize(kind:, records:, identity_index_cache: nil, transition: nil)
97
- unless SUPPORTED_KINDS.include?(kind)
73
+ # Identifies this snapshot for internal carry-forward (see
74
+ # CollectionTransition). A token of its own, as `object_id` is unique
75
+ # only among live objects: Ruby may hand a collected snapshot's id to a
76
+ # later one.
77
+ attr_reader :serial #: Object
78
+
79
+ # `ordered` says the records are already in documented order, as a
80
+ # transition's are: checking them again for each event made a replay's
81
+ # time grow with its events times the size of the collection they changed.
82
+ #: (kind: Symbol, records: Array[RecordSnapshot], ?identity_check: untyped, ?transition: CollectionTransition?, ?ordered: bool) -> void
83
+ def initialize(kind:, records:, identity_check: nil, transition: nil, ordered: false)
84
+ unless SUPPORTED_ASSOCIATION_MACROS.include?(kind)
98
85
  raise ArgumentError, "unsupported association kind: #{kind.inspect}"
99
86
  end
100
87
  if !self.class.collection_kind?(kind) && records.length > 1
@@ -102,25 +89,30 @@ module PaperTrailDiff
102
89
  end
103
90
 
104
91
  @kind = kind
105
- @records = ordered(records)
106
- @identity_index_cache = identity_index_cache || IdentityIndexCache.new
92
+ @records = ordered ? in_order(records) : ordered(records)
93
+ @identity_check = identity_check || IdentityCheck.new
94
+ @identity_index = CollectionIdentityIndex.new(@records)
107
95
  @transition = transition
108
- @serial = SERIALS.next_serial
96
+ @serial = Object.new
109
97
  freeze
110
98
  end
111
99
 
112
- # Builds a structurally adjacent collection snapshot for internal activity carry-forward.
113
- #: (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?, membership_preserved: bool) -> AssociationSnapshot
114
- def transition_to(records, before:, after:, membership_preserved:)
115
- cache = membership_preserved ? @identity_index_cache : nil
100
+ # Builds a structurally adjacent collection snapshot for internal activity
101
+ # carry-forward. Its records are this one's with one of them replaced in
102
+ # its place, taken out, or put in where its identity sorts, so they are in
103
+ # order, and as distinct as these unless the record put in repeats one
104
+ # beside it.
105
+ #: (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?) -> AssociationSnapshot
106
+ def transition_to(records, before:, after:)
116
107
  transition = if before || after
117
108
  CollectionTransition.new(from: self, before: before, after: after)
118
109
  end
119
110
  self.class.new(
120
111
  kind: kind,
121
112
  records: records,
122
- identity_index_cache: cache,
123
- transition: transition
113
+ identity_check: (@identity_check unless after && repeated?(records, after)),
114
+ transition: transition,
115
+ ordered: true
124
116
  )
125
117
  end
126
118
 
@@ -131,7 +123,7 @@ module PaperTrailDiff
131
123
  keys = records.map { |record| Support.sortable_identity(record.type, record.id) }
132
124
  return records.sort_by.with_index { |_, index| keys.fetch(index) }.freeze unless sorted?(keys)
133
125
 
134
- records.frozen? ? records : records.dup.freeze
126
+ in_order(records)
135
127
  end
136
128
 
137
129
  #: (Array[Array[untyped]]) -> bool
@@ -146,17 +138,17 @@ module PaperTrailDiff
146
138
 
147
139
  #: (untyped, untyped) -> Integer?
148
140
  def position(type, id)
149
- identity_index.position(type, id)
141
+ @identity_index.position(type, id)
150
142
  end
151
143
 
152
144
  #: (untyped) -> Integer?
153
145
  def position_for_id(id)
154
- identity_index.position_for_id(id)
146
+ @identity_index.position_for_id(id)
155
147
  end
156
148
 
157
149
  #: () -> void
158
150
  def validate_unique_identities!
159
- identity_index
151
+ @identity_check.call(records)
160
152
  nil
161
153
  end
162
154
 
@@ -167,12 +159,22 @@ module PaperTrailDiff
167
159
 
168
160
  private
169
161
 
170
- # @rbs @identity_index_cache: untyped
162
+ # @rbs @identity_check: untyped
163
+ # @rbs @identity_index: CollectionIdentityIndex
171
164
  # @rbs @transition: CollectionTransition?
172
165
 
173
- #: () -> CollectionIdentityIndex
174
- def identity_index
175
- @identity_index_cache.index(records)
166
+ #: (Array[RecordSnapshot]) -> Array[RecordSnapshot]
167
+ def in_order(records)
168
+ records.frozen? ? records : records.dup.freeze
169
+ end
170
+
171
+ # Whether the records hold this record's identity twice: a second one
172
+ # follows the first in their order.
173
+ #: (Array[RecordSnapshot], RecordSnapshot) -> bool
174
+ def repeated?(records, record)
175
+ first = CollectionIdentityIndex.new(records).insertion(record.type, record.id)
176
+ twin = records[first + 1]
177
+ !twin.nil? && twin.identity.eql?(record.identity)
176
178
  end
177
179
  end
178
180
 
@@ -0,0 +1,115 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # The records one snapshot of a root holds under each of its associations,
6
+ # at any depth, kept up as a replay moves from each snapshot to the next.
7
+ #
8
+ # Looking through a snapshot for a record means reading every collection in
9
+ # it, and a replay asks for each of its events, so its time grew with its
10
+ # events times the records of the tree. A snapshot differs from the one
11
+ # before it by the record its event changed, which the collections say
12
+ # (see AssociationSnapshot#transition_to), so moving costs what changed.
13
+ #
14
+ # A record can be in a tree at several places, so each is counted.
15
+ class SnapshotMembers
16
+ #: () -> void
17
+ def initialize
18
+ @snapshot = nil
19
+ @counts = {} #: Hash[String, Hash[String, Hash[String, Integer]]]
20
+ end
21
+
22
+ #: (RecordSnapshot?) -> void
23
+ def move_to(snapshot)
24
+ before = @snapshot&.associations || {}
25
+ after = snapshot&.associations || {}
26
+ (before.keys | after.keys).each do |name|
27
+ change(@counts[name] ||= {}, before[name], after[name])
28
+ end
29
+ @snapshot = snapshot
30
+ end
31
+
32
+ # Whether a record of one of the types is under one of the root's
33
+ # associations named. Ids match by their text, as a collection's do.
34
+ #: (Array[String], Array[String?], untyped) -> bool
35
+ def holds?(branches, types, id)
36
+ text = id.to_s
37
+ branches.any? do |name|
38
+ counts = @counts[name]
39
+ !counts.nil? && types.any? { |type| counts[type.to_s]&.key?(text) }
40
+ end
41
+ end
42
+
43
+ private
44
+
45
+ # @rbs @snapshot: RecordSnapshot?
46
+ # @rbs @counts: Hash[String, Hash[String, Hash[String, Integer]]]
47
+
48
+ #: (Hash[String, Hash[String, Integer]], AssociationSnapshot?, AssociationSnapshot?) -> void
49
+ def change(counts, before, after)
50
+ return if before.equal?(after)
51
+
52
+ transition = (after.transition_from(before) if before && after)
53
+ return replace(counts, transition.before, transition.after) if transition
54
+
55
+ compare(counts, before ? before.records : [], after ? after.records : [])
56
+ end
57
+
58
+ # Two collections with no transition between them share the records
59
+ # before and after those that changed.
60
+ #: (Hash[String, Hash[String, Integer]], Array[RecordSnapshot], Array[RecordSnapshot]) -> void
61
+ def compare(counts, before, after)
62
+ head = shared(before, after)
63
+ tail = shared(before.drop(head).reverse, after.drop(head).reverse)
64
+ exchange(counts, before[head, before.length - head - tail] || [],
65
+ after[head, after.length - head - tail] || [])
66
+ end
67
+
68
+ # How many records two lists begin with alike.
69
+ #: (Array[RecordSnapshot], Array[RecordSnapshot]) -> Integer
70
+ def shared(left, right)
71
+ limit = [left.length, right.length].min
72
+ (0...limit).find { |index| !left.fetch(index).equal?(right.fetch(index)) } || limit
73
+ end
74
+
75
+ #: (Hash[String, Hash[String, Integer]], Array[RecordSnapshot], Array[RecordSnapshot]) -> void
76
+ def exchange(counts, before, after)
77
+ return replace(counts, before.first, after.first) if before.length == 1 && after.length == 1
78
+
79
+ before.each { |record| count(counts, record, -1) }
80
+ after.each { |record| count(counts, record, 1) }
81
+ end
82
+
83
+ # A record that stays is followed into its collections; another is taken
84
+ # out, or put in, with everything it holds.
85
+ #: (Hash[String, Hash[String, Integer]], RecordSnapshot?, RecordSnapshot?) -> void
86
+ def replace(counts, before, after)
87
+ if before && after && before.identity.eql?(after.identity)
88
+ follow(counts, before, after)
89
+ else
90
+ count(counts, before, -1)
91
+ count(counts, after, 1)
92
+ end
93
+ end
94
+
95
+ #: (Hash[String, Hash[String, Integer]], RecordSnapshot, RecordSnapshot) -> void
96
+ def follow(counts, before, after)
97
+ (before.associations.keys | after.associations.keys).each do |name|
98
+ change(counts, before.associations[name], after.associations[name])
99
+ end
100
+ end
101
+
102
+ #: (Hash[String, Hash[String, Integer]], RecordSnapshot?, Integer) -> void
103
+ def count(counts, record, by)
104
+ return unless record
105
+
106
+ ids = counts[record.type] ||= {}
107
+ text = record.id.to_s
108
+ held = ids.fetch(text, 0) + by
109
+ held.zero? ? ids.delete(text) : ids[text] = held
110
+ record.associations.each_value do |association|
111
+ association.records.each { |nested| count(counts, nested, by) }
112
+ end
113
+ end
114
+ end
115
+ end
@@ -67,17 +67,6 @@ module PaperTrailDiff
67
67
  normalize_record(record, @tree, '', reifier, reflections)
68
68
  end
69
69
 
70
- # Normalizes one member of an already selected association branch.
71
- #: (untyped, tree: AssociationTree, path: String, incoming: untyped, reifier: untyped) -> RecordSnapshot?
72
- def call_child(record, tree:, path:, incoming:, reifier:)
73
- return unless record
74
-
75
- @structural_columns[path] ||= @traversal.incoming_relationship_columns(incoming)
76
- reflections = reflections_for(record, tree, path)
77
- reifier.reify(record, reflections) unless reflections.empty?
78
- normalize_record(record, tree, path, reifier, reflections)
79
- end
80
-
81
70
  # Normalizes scalar attributes without traversing or loading associations.
82
71
  #: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
83
72
  def attributes_for(record, tree:, path:)
@@ -41,11 +41,7 @@ module PaperTrailDiff
41
41
  # types alike; each boundary carries its own `version_id`.
42
42
  #: (?metadata: bool) -> Hash[Symbol, untyped]
43
43
  def to_h(metadata: false)
44
- {
45
- from: from_boundary.to_h(metadata: metadata),
46
- to: to_boundary.to_h(metadata: metadata),
47
- diff: diff.to_h
48
- }
44
+ ActivityBoundary.transition_h(from_boundary, to_boundary, diff, metadata: metadata)
49
45
  end
50
46
  end
51
47
  end