paper_trail_diff 0.13.1 → 0.15.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 (181) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +630 -0
  3. data/QUICKSTART.md +30 -10
  4. data/README.md +91 -13
  5. data/docs/architecture.md +62 -18
  6. data/docs/performance.md +116 -298
  7. data/docs/reference.md +554 -102
  8. data/docs/testing.md +93 -14
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +19 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +11 -1
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +16 -2
  14. data/lib/paper_trail_diff/activity_event.rb +41 -10
  15. data/lib/paper_trail_diff/activity_event_record_resolver.rb +20 -1
  16. data/lib/paper_trail_diff/activity_event_route_finder.rb +2 -1
  17. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +1 -1
  18. data/lib/paper_trail_diff/activity_history.rb +34 -9
  19. data/lib/paper_trail_diff/activity_range.rb +32 -5
  20. data/lib/paper_trail_diff/activity_relationship.rb +12 -0
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +5 -2
  22. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  23. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +131 -0
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +281 -120
  25. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  27. data/lib/paper_trail_diff/activity_version_collector.rb +37 -24
  28. data/lib/paper_trail_diff/activity_view.rb +69 -0
  29. data/lib/paper_trail_diff/analysis.rb +13 -1
  30. data/lib/paper_trail_diff/analysis_batch.rb +24 -30
  31. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  32. data/lib/paper_trail_diff/association_activity_edge.rb +236 -0
  33. data/lib/paper_trail_diff/association_activity_selection.rb +197 -0
  34. data/lib/paper_trail_diff/association_discovery.rb +14 -11
  35. data/lib/paper_trail_diff/association_key.rb +56 -0
  36. data/lib/paper_trail_diff/association_traversal.rb +180 -47
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  38. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  39. data/lib/paper_trail_diff/batched_root_analyzer.rb +12 -14
  40. data/lib/paper_trail_diff/batched_root_versions.rb +53 -47
  41. data/lib/paper_trail_diff/change_row.rb +133 -0
  42. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  43. data/lib/paper_trail_diff/comparison_batch.rb +37 -10
  44. data/lib/paper_trail_diff/configuration.rb +35 -12
  45. data/lib/paper_trail_diff/deleted_analysis_batch.rb +45 -27
  46. data/lib/paper_trail_diff/deleted_root_filter.rb +79 -0
  47. data/lib/paper_trail_diff/deprecation.rb +61 -0
  48. data/lib/paper_trail_diff/diagnostics.rb +105 -102
  49. data/lib/paper_trail_diff/direct_record_state_loader.rb +10 -1
  50. data/lib/paper_trail_diff/endpoint.rb +26 -3
  51. data/lib/paper_trail_diff/errors.rb +5 -2
  52. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  53. data/lib/paper_trail_diff/habtm_transaction_owners.rb +68 -0
  54. data/lib/paper_trail_diff/historical_association_reifier.rb +34 -6
  55. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +63 -76
  57. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +12 -13
  58. data/lib/paper_trail_diff/live_graph_collector.rb +1 -1
  59. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  60. data/lib/paper_trail_diff/paper_trail_adapter.rb +136 -125
  61. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +14 -2
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +110 -36
  63. data/lib/paper_trail_diff/prepared_edge_loader.rb +31 -46
  64. data/lib/paper_trail_diff/prepared_history.rb +70 -53
  65. data/lib/paper_trail_diff/prepared_history_loader.rb +34 -43
  66. data/lib/paper_trail_diff/prepared_record_index.rb +64 -7
  67. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +1 -1
  68. data/lib/paper_trail_diff/prepared_state_association_reader.rb +119 -29
  69. data/lib/paper_trail_diff/recorded_changes.rb +83 -0
  70. data/lib/paper_trail_diff/recorded_class.rb +53 -0
  71. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  72. data/lib/paper_trail_diff/scope_condition.rb +386 -0
  73. data/lib/paper_trail_diff/scope_ranking.rb +206 -0
  74. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  75. data/lib/paper_trail_diff/scoped_analysis_builder.rb +20 -11
  76. data/lib/paper_trail_diff/scoped_root_selection.rb +105 -49
  77. data/lib/paper_trail_diff/snapshot.rb +16 -1
  78. data/lib/paper_trail_diff/snapshot_normalizer.rb +10 -3
  79. data/lib/paper_trail_diff/support.rb +38 -6
  80. data/lib/paper_trail_diff/time_range.rb +37 -18
  81. data/lib/paper_trail_diff/time_version_range.rb +5 -5
  82. data/lib/paper_trail_diff/timeline_builder.rb +7 -7
  83. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  84. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  85. data/lib/paper_trail_diff/transaction_cut.rb +181 -0
  86. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  87. data/lib/paper_trail_diff/version.rb +1 -1
  88. data/lib/paper_trail_diff/version_association_candidate_scope.rb +13 -3
  89. data/lib/paper_trail_diff/version_boundary.rb +37 -8
  90. data/lib/paper_trail_diff/version_query.rb +34 -10
  91. data/lib/paper_trail_diff/version_range.rb +8 -15
  92. data/lib/paper_trail_diff/version_scope_filter.rb +20 -13
  93. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +31 -16
  94. data/lib/paper_trail_diff/version_table.rb +60 -0
  95. data/lib/paper_trail_diff.rb +126 -55
  96. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +10 -2
  97. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  98. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +5 -0
  99. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +5 -0
  100. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  101. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +7 -0
  102. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  103. data/sig/generated/paper_trail_diff/activity_range.rbs +14 -3
  104. data/sig/generated/paper_trail_diff/activity_relationship.rbs +3 -0
  105. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +2 -0
  106. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  107. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +79 -0
  108. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -28
  109. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  110. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +12 -4
  111. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  112. data/sig/generated/paper_trail_diff/analysis.rbs +8 -1
  113. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  114. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  115. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +148 -0
  116. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +112 -0
  117. data/sig/generated/paper_trail_diff/association_discovery.rbs +8 -5
  118. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  119. data/sig/generated/paper_trail_diff/association_traversal.rbs +88 -9
  120. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  121. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -10
  122. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -10
  123. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  124. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  125. data/sig/generated/paper_trail_diff/comparison_batch.rbs +22 -4
  126. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  127. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +20 -8
  128. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +48 -0
  129. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  130. data/sig/generated/paper_trail_diff/diagnostics.rbs +44 -32
  131. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +6 -0
  132. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  133. data/sig/generated/paper_trail_diff/errors.rbs +5 -2
  134. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  135. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +40 -0
  136. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +13 -0
  137. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  138. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +36 -30
  139. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +5 -3
  140. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  141. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +55 -48
  142. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  143. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +52 -10
  144. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -12
  145. data/sig/generated/paper_trail_diff/prepared_history.rbs +40 -24
  146. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +15 -13
  147. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +34 -2
  148. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +56 -11
  149. data/sig/generated/paper_trail_diff/recorded_changes.rbs +47 -0
  150. data/sig/generated/paper_trail_diff/recorded_class.rbs +22 -0
  151. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  152. data/sig/generated/paper_trail_diff/scope_condition.rbs +219 -0
  153. data/sig/generated/paper_trail_diff/scope_ranking.rbs +125 -0
  154. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  155. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +8 -3
  156. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -11
  157. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  158. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +6 -0
  159. data/sig/generated/paper_trail_diff/support.rbs +20 -2
  160. data/sig/generated/paper_trail_diff/time_range.rbs +20 -2
  161. data/sig/generated/paper_trail_diff/time_version_range.rbs +4 -4
  162. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  163. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  164. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  165. data/sig/generated/paper_trail_diff/transaction_cut.rbs +94 -0
  166. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  167. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +7 -0
  168. data/sig/generated/paper_trail_diff/version_boundary.rbs +20 -3
  169. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  170. data/sig/generated/paper_trail_diff/version_range.rbs +4 -2
  171. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +7 -4
  172. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -9
  173. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  174. data/sig/generated/paper_trail_diff.rbs +47 -25
  175. metadata +62 -10
  176. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  177. data/lib/paper_trail_diff/batch_safety.rb +0 -55
  178. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -224
  179. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  180. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -24
  181. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -43,12 +43,20 @@ module PaperTrailDiff
43
43
  end
44
44
  end
45
45
 
46
- #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer) -> void
47
- def initialize(scope, time_range:, limit:, historical_filter: nil,
48
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT)
46
+ # `activity_tree` names the association paths whose changes also select a
47
+ # root, as an activity analysis reports them. Without one, only a root's
48
+ # own versions select it.
49
+ #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
50
+ def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
51
+ max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil)
49
52
  @scope = normalize_scope(scope)
53
+ reject_unversioned!
50
54
  @time_range = time_range
51
55
  @limit = validate_limit(limit)
56
+ @related = if activity_tree
57
+ AssociationActivitySelection.new(model, tree: activity_tree,
58
+ time_range: time_range)
59
+ end
52
60
  @historical_filter = unless historical_filter.nil?
53
61
  HistoricalFilter.new(base_class, predicate: historical_filter,
54
62
  time_range: time_range, limit: @limit,
@@ -58,17 +66,11 @@ module PaperTrailDiff
58
66
 
59
67
  #: () -> Result
60
68
  def call
61
- return database_selection if @historical_filter.nil? && comparable_keys?
69
+ related = @related&.call || []
70
+ queries = subqueries(related)
71
+ return database_selection(queries) if queries
62
72
 
63
- candidates = versioned_ids
64
- candidates = @historical_filter.call(candidates) if @historical_filter && candidates.any?
65
- return Result.new(records: [], unreachable: []) if candidates.empty?
66
-
67
- live = live_ids(candidates)
68
- Result.new(
69
- records: selected_records(live),
70
- unreachable: (candidates - live).map { |id| identity(id) }.freeze
71
- )
73
+ plucked_selection(versioned_ids | AssociationActivitySelection.values(related).map(&:to_s))
72
74
  end
73
75
 
74
76
  private
@@ -77,43 +79,80 @@ module PaperTrailDiff
77
79
  # @rbs @time_range: TimeRange?
78
80
  # @rbs @limit: Integer
79
81
  # @rbs @historical_filter: untyped
82
+ # @rbs @related: AssociationActivitySelection?
80
83
 
81
84
  # Leaves the candidate set in the database. Plucking every root changed in
82
85
  # the window would cost memory and a statement proportional to all activity
83
86
  # in the window -- not to the relation or `limit:` -- so a report on one
84
87
  # record could read every id in a busy table. A subquery keeps the work
85
88
  # bounded by what the relation and the deletions actually contain.
86
- #: () -> Result
87
- def database_selection
88
- candidates = window_versions.select(:item_id)
89
+ #: (Array[AssociationActivitySelection::Query]) -> Result
90
+ def database_selection(related)
91
+ candidates = [window_versions.select(:item_id)] + related.map(&:relation)
92
+ missing = (missing_ids + related_missing_ids(related)).uniq.sort
89
93
  Result.new(
90
94
  records: selected_records(candidates),
91
- unreachable: missing_ids.map { |id| identity(id) }.freeze
95
+ unreachable: missing.map { |id| identity(id) }.freeze
92
96
  )
93
97
  end
94
98
 
99
+ # Comparing in SQL needs every subquery's column to share the key's type.
100
+ #: (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
101
+ def subqueries(related)
102
+ return unless @historical_filter.nil? && comparable_keys?
103
+
104
+ queries = related.grep(AssociationActivitySelection::Query) #: Array[AssociationActivitySelection::Query]
105
+ matching = queries.select { |ids| ids.type == key_type }
106
+ matching if matching.length == related.length
107
+ end
108
+
109
+ # Which candidates still have a row is asked without the relation's
110
+ # conditions, so that "filtered out" and "no longer exists" stay
111
+ # separable. A filter then reads the history of the relation's records
112
+ # only, whose order and page choose among those that match, and of the
113
+ # deleted ones, which no relation can test. Those it lists, as without a
114
+ # filter, but does not count toward `limit:`.
115
+ #: (Array[String]) -> Result
116
+ def plucked_selection(candidates)
117
+ live = ids_in(base_class.unscoped, candidates)
118
+ missing = candidates - live
119
+ if (filter = @historical_filter)
120
+ live = filter.call(ids_in(@scope.except(:order, :limit, :offset), live).uniq)
121
+ missing = filter.call(missing, counted: false)
122
+ end
123
+ Result.new(records: selected_records([live]),
124
+ unreachable: missing.sort.map { |id| identity(id) }.freeze)
125
+ end
126
+
95
127
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
96
- # rejects an integer key against a string item_id outright.
128
+ # rejects an integer key against a string item_id outright. A composite
129
+ # key names no single attribute, so it has no type and never matches.
97
130
  #: () -> bool
98
131
  def comparable_keys?
99
- return false unless primary_key.is_a?(String)
132
+ version_class.type_for_attribute('item_id').type == key_type
133
+ end
100
134
 
101
- item_id = version_class.columns_hash['item_id']&.type
102
- key = base_class.columns_hash[primary_key]&.type
103
- !item_id.nil? && item_id == key
135
+ #: () -> Symbol?
136
+ def key_type
137
+ base_class.type_for_attribute(primary_key).type
138
+ end
139
+
140
+ #: (Array[AssociationActivitySelection::Query]) -> Array[String]
141
+ def related_missing_ids(related)
142
+ live = base_class.unscoped.select(primary_key).arel
143
+ related.flat_map { |ids| ids.missing(live) }.map(&:to_s)
104
144
  end
105
145
 
106
146
  # Changed in the window but without a row, found with an anti-join instead
107
147
  # of comparing two plucked lists.
108
148
  #: () -> Array[String]
109
149
  def missing_ids
110
- live = base_class.unscoped.select(primary_key)
111
- window_versions.where.not(item_id: live).distinct.pluck(:item_id).map(&:to_s).uniq.sort
150
+ window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
112
151
  end
113
152
 
114
153
  #: () -> untyped
115
154
  def window_versions
116
- relation = version_class.where(item_type: item_type)
155
+ relation = VersionQuery.for_model(model)
117
156
  range = @time_range
118
157
  range ? range.scope(relation) : relation
119
158
  end
@@ -127,16 +166,21 @@ module PaperTrailDiff
127
166
  raise ConfigurationError, 'scope: must be an ActiveRecord relation or model class'
128
167
  end
129
168
 
130
- relation = scope.all
131
- return relation if Support.versioned?(relation.model)
169
+ scope.all
170
+ end
171
+
172
+ #: () -> void
173
+ def reject_unversioned!
174
+ return if Support.versioned?(model)
132
175
 
133
176
  raise UnversionedAssociationError,
134
- "scope: #{relation.model.name} is not versioned, so it has no history to select from"
177
+ "scope: #{model} is not versioned, so it has no history to select from"
135
178
  end
136
179
 
180
+ # No Integer subclass has instances, so this is `is_a?` by another name.
137
181
  #: (Integer) -> Integer
138
182
  def validate_limit(limit)
139
- return limit if limit.is_a?(Integer) && limit.positive?
183
+ return limit if limit.instance_of?(Integer) && limit.positive?
140
184
 
141
185
  raise ConfigurationError, 'limit: must be a positive Integer'
142
186
  end
@@ -146,29 +190,28 @@ module PaperTrailDiff
146
190
  # version table alone so that it does not depend on rows still existing.
147
191
  #: () -> Array[String]
148
192
  def versioned_ids
149
- window_versions.distinct.pluck(:item_id).map(&:to_s).uniq
193
+ window_versions.distinct.pluck(:item_id).map(&:to_s)
150
194
  end
151
195
 
152
- # Which of those candidates still have a row, asked without the relation's
153
- # conditions so that "filtered out" and "no longer exists" stay separable.
154
- #: (Array[String]) -> Array[String]
155
- def live_ids(candidates)
196
+ #: (untyped, Array[String]) -> Array[String]
197
+ def ids_in(relation, candidates)
156
198
  candidates.each_slice(PAGE_SIZE).flat_map do |slice|
157
- base_class.unscoped.where(primary_key => slice).pluck(primary_key).map(&:to_s)
199
+ relation.where(primary_key => slice).pluck(primary_key).map(&:to_s)
158
200
  end
159
201
  end
160
202
 
161
203
  # Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
162
204
  # relation may order by joined columns or select a PostgreSQL json column.
163
205
  # Read bounded pages until the relation ends or too many unique roots appear.
164
- #: (untyped) -> Array[untyped]
165
- def selected_records(live)
166
- return [] if live.is_a?(Array) && live.empty?
167
-
206
+ # Each candidate source is an id list or a subquery; a record matching any
207
+ # of them is selected.
208
+ #: (Array[untyped]) -> Array[untyped]
209
+ def selected_records(candidates)
210
+ relation = candidate_relation(candidates)
168
211
  records = {} #: Hash[untyped, untyped]
169
212
  consumed = 0
170
213
  loop do
171
- page = record_page(live, consumed)
214
+ page = record_page(relation, consumed)
172
215
  page.each { |record| records[record.id] ||= record }
173
216
  reject_oversized!(records.length)
174
217
  break if page.length < PAGE_SIZE
@@ -178,15 +221,20 @@ module PaperTrailDiff
178
221
  records.values.freeze
179
222
  end
180
223
 
224
+ #: (Array[untyped]) -> untyped
225
+ def candidate_relation(candidates)
226
+ candidates.map do |ids|
227
+ conditions = { primary_key => ids } #: Hash[untyped, untyped]
228
+ ordered_scope.where(conditions)
229
+ end.reduce(:or)
230
+ end
231
+
181
232
  #: (untyped, Integer) -> Array[untyped]
182
- def record_page(live, consumed)
233
+ def record_page(relation, consumed)
183
234
  count = page_limit(consumed)
184
235
  return [] if count.zero?
185
236
 
186
- # An id list or a candidate subquery; both read the same way in SQL.
187
- conditions = { primary_key => live } #: Hash[untyped, untyped]
188
- ordered_scope.where(conditions)
189
- .offset((@scope.offset_value || 0) + consumed).limit(count).to_a
237
+ relation.offset((@scope.offset_value || 0) + consumed).limit(count)
190
238
  end
191
239
 
192
240
  # Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
@@ -220,22 +268,30 @@ module PaperTrailDiff
220
268
 
221
269
  #: () -> String
222
270
  def item_type
223
- base_class.name.to_s
271
+ base_class.name
272
+ end
273
+
274
+ # A relation delegates class methods to its model, so every mutation here,
275
+ # which drops `.model`, answers the same.
276
+ # mutant:disable
277
+ #: () -> untyped
278
+ def model
279
+ @scope.model
224
280
  end
225
281
 
226
282
  #: () -> untyped
227
283
  def base_class
228
- @scope.model.base_class
284
+ model.base_class
229
285
  end
230
286
 
231
287
  #: () -> untyped
232
288
  def primary_key
233
- @scope.model.primary_key
289
+ model.primary_key
234
290
  end
235
291
 
236
292
  #: () -> untyped
237
293
  def version_class
238
- @scope.model.paper_trail.version_class
294
+ model.paper_trail.version_class
239
295
  end
240
296
  end
241
297
  end
@@ -102,7 +102,7 @@ module PaperTrailDiff
102
102
  end
103
103
 
104
104
  @kind = kind
105
- @records = records.frozen? ? records : records.dup.freeze
105
+ @records = ordered(records)
106
106
  @identity_index_cache = identity_index_cache || IdentityIndexCache.new
107
107
  @transition = transition
108
108
  @serial = SERIALS.next_serial
@@ -124,6 +124,21 @@ module PaperTrailDiff
124
124
  )
125
125
  end
126
126
 
127
+ # Collections are documented in record type, then ID, order wherever they
128
+ # were read from. Most arrive sorted, so they are checked before sorting.
129
+ #: (Array[RecordSnapshot]) -> Array[RecordSnapshot]
130
+ def ordered(records)
131
+ keys = records.map { |record| Support.sortable_identity(record.type, record.id) }
132
+ return records.sort_by.with_index { |_, index| keys.fetch(index) }.freeze unless sorted?(keys)
133
+
134
+ records.frozen? ? records : records.dup.freeze
135
+ end
136
+
137
+ #: (Array[Array[untyped]]) -> bool
138
+ def sorted?(keys)
139
+ keys.each_cons(2).all? { |left, right| (left <=> right).to_i <= 0 }
140
+ end
141
+
127
142
  #: (AssociationSnapshot) -> CollectionTransition?
128
143
  def transition_from(association)
129
144
  @transition if @transition&.from?(association)
@@ -200,9 +200,8 @@ module PaperTrailDiff
200
200
  path,
201
201
  reifier
202
202
  )
203
- # A reified history can hold a member PaperTrail could not rebuild.
204
- records = Array(record.public_send(reflection.name)).compact
205
- child_path = Support.association_path(path, reflection.name.to_s)
203
+ records = members(record, reflection)
204
+ child_path = Support.association_path(path, reflection.name)
206
205
  @structural_columns[child_path] ||= @traversal.incoming_relationship_columns(reflection)
207
206
  snapshot = AssociationSnapshot.new(
208
207
  kind: reflection.macro,
@@ -211,6 +210,14 @@ module PaperTrailDiff
211
210
  @pool.association(child_path, snapshot)
212
211
  end
213
212
 
213
+ # A reified history can hold a member PaperTrail could not rebuild. A
214
+ # through loads a record once per join that reaches it; it is one member,
215
+ # as Active Record compares records by class and id.
216
+ #: (untyped, untyped) -> Array[untyped]
217
+ def members(record, reflection)
218
+ Array(record.public_send(reflection.name)).compact.uniq
219
+ end
220
+
214
221
  #: (Array[untyped], AssociationTree, String, untyped) -> Array[RecordSnapshot]
215
222
  def normalize_children(records, tree, path, reifier)
216
223
  reflections_by_class = {} #: Hash[untyped, Array[untyped]]
@@ -3,7 +3,7 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Internal helpers for isolating and serializing values held by result objects.
6
- module Support
6
+ module Support # rubocop:disable Metrics/ModuleLength
7
7
  module_function
8
8
 
9
9
  #: (untyped) -> untyped
@@ -44,9 +44,28 @@ module PaperTrailDiff
44
44
  end
45
45
  end
46
46
 
47
+ # Records sort by type first so that mixed id types stay comparable, then
48
+ # naturally within one type. Ordering by the printed form instead would put
49
+ # id 10 before id 2, which is deterministic but reads as unsorted wherever a
50
+ # result is rendered.
51
+ #: (untyped, untyped) -> Array[untyped]
52
+ def sortable_identity(type, id)
53
+ key = case id
54
+ when Numeric then [0, id]
55
+ when String, Symbol then [1, id.to_s]
56
+ else [2, id.inspect]
57
+ end
58
+ [type.to_s, key]
59
+ end
60
+
47
61
  #: (untyped) -> Array[untyped]
48
62
  def chronological_version_key(version)
49
- [version.created_at, version.id.to_s.rjust(32, '0')]
63
+ version_key(version.created_at, version.id)
64
+ end
65
+
66
+ #: (untyped, untyped) -> Array[untyped]
67
+ def version_key(created_at, id)
68
+ [created_at, id.to_s.rjust(32, '0')]
50
69
  end
51
70
 
52
71
  # Ordering falls back to the id whenever timestamps tie, which recovers the
@@ -65,11 +84,24 @@ module PaperTrailDiff
65
84
  #: (Array[untyped]) -> Array[untyped]?
66
85
  def ambiguous_pair(sorted)
67
86
  sorted.each_cons(2).find do |left, right|
68
- left.created_at == right.created_at &&
69
- !(sequential_id?(left.id) && sequential_id?(right.id))
87
+ left.created_at == right.created_at && !orderable_tie?(left, right)
70
88
  end
71
89
  end
72
90
 
91
+ # Ids order versions saved in one instant only when they count up in one
92
+ # table. Two version tables count separately, so ids there say nothing.
93
+ #: (untyped, untyped) -> bool
94
+ def orderable_tie?(left, right)
95
+ version_table(left) == version_table(right) &&
96
+ sequential_id?(left.id) && sequential_id?(right.id)
97
+ end
98
+
99
+ #: (untyped) -> untyped
100
+ def version_table(version)
101
+ version.class.respond_to?(:table_name) ? version.class.table_name : version.class.name
102
+ end
103
+ private_class_method :version_table
104
+
73
105
  # Versions sharing a timestamp, whether or not their ids order them. PT-AT
74
106
  # indexes association membership per version but resolves it by timestamp,
75
107
  # so association state cannot be told apart across such a pair even when the
@@ -124,9 +156,9 @@ module PaperTrailDiff
124
156
  raise(ConfigurationError, 'versions have incomparable timestamps')
125
157
  end
126
158
 
127
- #: (String, String) -> String
159
+ #: (String, String | Symbol) -> String
128
160
  def association_path(parent, name)
129
- parent.empty? ? name : "#{parent}.#{name}"
161
+ parent.empty? ? name.to_s : "#{parent}.#{name}"
130
162
  end
131
163
 
132
164
  #: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
@@ -3,6 +3,10 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Validates and applies a finite wall-clock range without loading model state.
6
+ #
7
+ # A Date is a whole day and a String a local time, both in Time.zone, as
8
+ # Rails reads them, or in UTC without one: never the server's own zone. An
9
+ # inclusive Date end runs through that day.
6
10
  class TimeRange
7
11
  attr_reader :begin_time #: Time
8
12
  attr_reader :end_time #: Time
@@ -14,8 +18,8 @@ module PaperTrailDiff
14
18
  end
15
19
 
16
20
  @begin_time = coerce_time(value.begin, boundary: :begin)
17
- @end_time = coerce_time(value.end, boundary: :end)
18
- @exclude_end = value.exclude_end?
21
+ @exclude_end = value.exclude_end? || calendar_date?(value.end)
22
+ @end_time = coerce_time(end_value(value), boundary: :end)
19
23
  validate_order!
20
24
  freeze
21
25
  end
@@ -40,8 +44,7 @@ module PaperTrailDiff
40
44
 
41
45
  #: (untyped) -> untyped
42
46
  def trailing_scope(relation)
43
- column = relation.klass.arel_table[:created_at]
44
- relation.where(after_end(column))
47
+ relation.where(after_end(relation.arel_table[:created_at]))
45
48
  end
46
49
 
47
50
  # Each item's earliest version after the range, keyed by item id. One row
@@ -49,11 +52,11 @@ module PaperTrailDiff
49
52
  # the query stays portable; a timestamp tie keeps the lower id.
50
53
  #: (untyped) -> Hash[String, untyped]
51
54
  def first_trailing_versions(relation)
52
- table = relation.klass.arel_table
55
+ table = relation.arel_table
53
56
  first_after = VersionQuery.no_earlier_version(table) do |earlier|
54
57
  after_end(earlier[:created_at])
55
58
  end
56
- versions = VersionQuery.chronological(trailing_scope(relation).where(first_after)).to_a
59
+ versions = VersionQuery.chronological(trailing_scope(relation).where(first_after))
57
60
  first = {} #: Hash[String, untyped]
58
61
  versions.each { |version| first[version.item_id.to_s] ||= version }
59
62
  first
@@ -75,23 +78,39 @@ module PaperTrailDiff
75
78
 
76
79
  #: (untyped, boundary: Symbol) -> Time
77
80
  def coerce_time(value, boundary:)
78
- unless value.respond_to?(:to_time)
79
- raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
80
- end
81
-
82
81
  time_value(value).getutc.freeze
83
- rescue ArgumentError, NoMethodError, TypeError => e
84
- raise InvalidTimeRangeError,
85
- "`within` #{boundary} must be time-like",
86
- cause: e
82
+ rescue ArgumentError, NoMethodError, TypeError
83
+ raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
87
84
  end
88
85
 
89
- #: (untyped) -> Time
86
+ # Anything else names its instant, and `getutc` reads it without
87
+ # `to_time`, which Active Support 8.0 and older warn will change on a
88
+ # zoned time, and without changing the caller's own value as `utc` does.
89
+ #: (untyped) -> untyped
90
90
  def time_value(value)
91
- return value if value.is_a?(Time)
91
+ return zone.parse(value) || raise(ArgumentError) if value.is_a?(String)
92
+ return zone.local(value.year, value.month, value.day) if calendar_date?(value)
93
+
94
+ value
95
+ end
96
+
97
+ # An inclusive date end runs through the day: to the next one's start.
98
+ #: (Range[untyped]) -> untyped
99
+ def end_value(range)
100
+ last = range.end
101
+ calendar_date?(last) && !range.exclude_end? ? last.next_day : last
102
+ end
103
+
104
+ # A DateTime is a Date too, but names its instant.
105
+ #: (untyped) -> bool
106
+ def calendar_date?(value)
107
+ value.instance_of?(Date)
108
+ end
92
109
 
93
- utc = value.utc if value.respond_to?(:utc)
94
- utc.is_a?(Time) ? utc : value.to_time
110
+ #: () -> untyped
111
+ def zone
112
+ time = Time #: untyped
113
+ time.zone || time.find_zone!('UTC')
95
114
  end
96
115
 
97
116
  #: () -> void
@@ -4,18 +4,18 @@
4
4
  module PaperTrailDiff
5
5
  # Selects in-range root versions plus one later reconstruction boundary.
6
6
  class TimeVersionRange
7
- #: (untyped, time_range: TimeRange, ?version_scope: untyped, ?live_endpoint: untyped) -> void
8
- def initialize(record, time_range:, version_scope: nil, live_endpoint: nil)
7
+ #: (untyped, time_range: TimeRange, version_scope: untyped, live_endpoint: untyped) -> void
8
+ def initialize(record, time_range:, version_scope:, live_endpoint:)
9
9
  @record = record
10
10
  @time_range = time_range
11
11
  @version_scope = version_scope
12
12
  @live_endpoint = live_endpoint
13
13
  end
14
14
 
15
- #: (?context_required: bool) -> RootVersionPlan
16
- def select_plan(context_required: false)
15
+ #: (context_required: bool) -> RootVersionPlan
16
+ def select_plan(context_required:)
17
17
  relation = Endpoint.versions(@record)
18
- in_range = ordered(@time_range.scope(relation).to_a)
18
+ in_range = ordered(@time_range.scope(relation))
19
19
  RootVersionSelection.new(
20
20
  in_range: in_range,
21
21
  selected: VersionScopeFilter.new(@version_scope).call(@time_range.scope(relation),
@@ -46,21 +46,21 @@ module PaperTrailDiff
46
46
  return empty_history if plan.empty?
47
47
 
48
48
  versions = plan.versions
49
- @snapshotter.prepare(@record, versions) if @snapshotter.respond_to?(:prepare)
50
- steps = build_steps(plan)
51
- final = plan.closes_on_destroy ? nil : @snapshotter.call(plan.final_endpoint)
52
- [steps, @snapshotter.call(versions.first), final]
49
+ snapshots = @snapshotter.prepare(@record, versions)
50
+ steps = build_steps(plan, snapshots)
51
+ final = plan.closes_on_destroy ? nil : snapshots.call(plan.final_endpoint)
52
+ [steps, snapshots.call(versions.first), final]
53
53
  end
54
54
 
55
- #: (RootVersionPlan) -> Array[Step]
56
- def build_steps(plan)
55
+ #: (RootVersionPlan, untyped) -> Array[Step]
56
+ def build_steps(plan, snapshots)
57
57
  captured_at = Time.now.utc if plan.closing_record
58
58
  plan.steps.map do |from_endpoint, to_endpoint|
59
59
  Step.new(
60
60
  from_version: from_endpoint,
61
61
  to_version: to_endpoint,
62
62
  captured_at: captured_at,
63
- diff: Engine.compare(@snapshotter.call(from_endpoint), @snapshotter.call(to_endpoint))
63
+ diff: Engine.compare(snapshots.call(from_endpoint), snapshots.call(to_endpoint))
64
64
  )
65
65
  end.freeze
66
66
  end
@@ -122,9 +122,17 @@ module PaperTrailDiff
122
122
  VersionQuery.chronological(Endpoint.versions(@record))
123
123
  end
124
124
 
125
+ # A batch passes each root the window it already moved to transaction
126
+ # edges; a single record's window is moved here.
125
127
  #: (untyped) -> TimeRange?
126
128
  def build_time_range(within)
127
- TimeRange.new(within) unless within.nil?
129
+ return if within.nil?
130
+ return within if within.instance_of?(TimeRange)
131
+
132
+ range = TimeRange.new(within)
133
+ return range unless Support.versioned?(@record.class)
134
+
135
+ TransactionCut.windows(@record.class, [@record], range).fetch(@record.id.to_s, range)
128
136
  end
129
137
 
130
138
  #: () -> void
@@ -2,22 +2,35 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
5
+ # Prepares the snapshot store for TimelineBuilder, one root at a time.
6
6
  class TimelineSnapshotProvider
7
7
  #: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
8
8
  def initialize(store, live_snapshotter:)
9
9
  @store = store
10
10
  @live_snapshotter = live_snapshotter
11
- @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
12
11
  end
13
12
 
14
- #: (untyped, Array[untyped]) -> void
13
+ #: (untyped, Array[untyped]) -> PreparedTimelineSnapshots
15
14
  def prepare(record, versions)
16
- # Adjacent steps share endpoints. Keep their immutable snapshots for this
17
- # root only, including nil create states, and release them before the next
18
- # root so batch memory does not retain every reconstructed graph.
19
- @snapshots.clear
20
- @store.prepare(record, versions)
15
+ history = @store.prepare(record, versions)
16
+ PreparedTimelineSnapshots.new(history, store: @store, live_snapshotter: @live_snapshotter)
17
+ end
18
+
19
+ # @rbs @store: HistoricalSnapshotStore
20
+ # @rbs @live_snapshotter: untyped
21
+ end
22
+
23
+ # One root's timeline snapshots, read with the history prepared for it.
24
+ # Adjacent steps share endpoints, so each immutable snapshot, including a
25
+ # nil create state, is kept for this root only and released with it, and
26
+ # batch memory does not retain every reconstructed graph.
27
+ class PreparedTimelineSnapshots
28
+ #: (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
29
+ def initialize(history, store:, live_snapshotter:)
30
+ @history = history
31
+ @store = store
32
+ @live_snapshotter = live_snapshotter
33
+ @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
21
34
  end
22
35
 
23
36
  # A window closing on current state ends at the live record rather than at a
@@ -28,19 +41,13 @@ module PaperTrailDiff
28
41
  return @snapshots[key] if @snapshots.key?(key)
29
42
 
30
43
  @snapshots[key] = if Endpoint.record?(endpoint)
31
- live_snapshot(endpoint)
44
+ @live_snapshotter.call(endpoint)
32
45
  else
33
- @store.uncached(endpoint, endpoint)
46
+ @store.uncached(endpoint, endpoint, history: @history)
34
47
  end
35
48
  end
36
49
 
37
- private
38
-
39
- #: (untyped) -> RecordSnapshot?
40
- def live_snapshot(record)
41
- @live_snapshotter.call(record)
42
- end
43
-
50
+ # @rbs @history: PreparedHistory?
44
51
  # @rbs @store: HistoricalSnapshotStore
45
52
  # @rbs @live_snapshotter: untyped
46
53
  # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]