paper_trail_diff 0.15.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -23,7 +23,6 @@ module PaperTrailDiff
23
23
  TEXT_TYPE = 'ActiveModel::Type::ImmutableString'
24
24
  ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
25
25
  BIND_PARAM = 'Arel::Nodes::BindParam'
26
- ATTRIBUTE = 'Arel::Attributes::Attribute'
27
26
  # Adapters that compare strings exactly by default. MySQL and SQL Server
28
27
  # ignore case and trailing spaces by default, which Ruby cannot follow.
29
28
  EXACT_TEXT_ADAPTERS = %w[sqlite3 postgresql].freeze
@@ -41,11 +40,9 @@ module PaperTrailDiff
41
40
  # A through also filters by the scopes of each reflection it passes.
42
41
  #: (untyped) -> bool
43
42
  def self.scoped_path?(reflection)
44
- return !reflection.scope.nil? if reflection.polymorphic?
45
- return true if scoped?(reflection)
46
- return false unless reflection.through_reflection?
47
-
48
- scoped_path?(reflection.through_reflection) || scoped_path?(reflection.source_reflection)
43
+ [reflection, *AssociationTraversal.through_parts(reflection)].any? do |part|
44
+ part.polymorphic? ? !part.scope.nil? : scoped?(part)
45
+ end
49
46
  end
50
47
 
51
48
  # Returns nil when the scope cannot be read as plain conditions and an
@@ -56,7 +53,7 @@ module PaperTrailDiff
56
53
  return if ranked && ranked_through?(reflection)
57
54
 
58
55
  relation = scoped_relation(reflection, model_class)
59
- return unless relation && plain_relation?(relation)
56
+ return unless relation && plain_relation?(relation, RELATION_VALUES)
60
57
 
61
58
  clause = relation.where_clause - model_class.unscoped.where_clause
62
59
  predicate = Reader.new(model_class).call(clause.ast)
@@ -70,11 +67,12 @@ module PaperTrailDiff
70
67
  # limit, and offset choose a page of current rows rather than membership,
71
68
  # and loading or selecting columns changes neither, so they are left out.
72
69
  # A single-table subclass's type condition is left to the caller, as for
73
- # an association.
70
+ # an association. `none` selects nothing, whatever it is chained to.
74
71
  #: (untyped, untyped) -> ScopeCondition?
75
72
  def self.for_relation(relation, model_class)
76
- extra = relation.values.except(*RELATION_VALUES, *LOADING_VALUES).values
77
- return unless extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
73
+ return nothing if relation.null_relation?
74
+
75
+ return unless plain_relation?(relation, [*RELATION_VALUES, *LOADING_VALUES])
78
76
 
79
77
  clause = relation.where_clause - model_class.unscoped.where_clause
80
78
  new(model_class, Reader.new(model_class).call(clause.ast))
@@ -82,6 +80,14 @@ module PaperTrailDiff
82
80
  nil
83
81
  end
84
82
 
83
+ # A relation `none` built, whose where clause is SQL text. A condition
84
+ # that matches nothing reads no attribute, so it names no model.
85
+ #: () -> ScopeCondition
86
+ def self.nothing
87
+ new(nil, [:or, []])
88
+ end
89
+ private_class_method :nothing
90
+
85
91
  # nil when the relation picks its members by conditions alone.
86
92
  #: (untyped, untyped, untyped) -> ScopeRanking?
87
93
  def self.ranking(relation, reflection, model_class)
@@ -105,11 +111,7 @@ module PaperTrailDiff
105
111
  # a has_one order.
106
112
  #: (untyped) -> bool
107
113
  def self.ranked_parts?(reflection)
108
- return false unless reflection.through_reflection?
109
-
110
- [reflection.through_reflection, reflection.source_reflection].any? do |part|
111
- ranked_part?(part) || ranked_parts?(part)
112
- end
114
+ AssociationTraversal.through_parts(reflection).any? { |part| ranked_part?(part) }
113
115
  end
114
116
 
115
117
  # A polymorphic part's class, and so its scope, is known only per record.
@@ -135,10 +137,10 @@ module PaperTrailDiff
135
137
  private_class_method :scoped_relation
136
138
 
137
139
  # Some parts, such as the having clause `or` sets, may be present but
138
- # empty.
139
- #: (untyped) -> bool
140
- def self.plain_relation?(relation)
141
- extra = relation.values.except(*RELATION_VALUES).values
140
+ # empty. `allowed` names the parts that may hold values.
141
+ #: (untyped, Array[Symbol]) -> bool
142
+ def self.plain_relation?(relation, allowed)
143
+ extra = relation.values.except(*allowed).values
142
144
  extra.all? { |value| value.respond_to?(:empty?) && value.empty? }
143
145
  end
144
146
  private_class_method :plain_relation?
@@ -158,6 +160,13 @@ module PaperTrailDiff
158
160
  evaluate(@predicate, attributes) == true
159
161
  end
160
162
 
163
+ # Whether no record can match, as for a relation `none` built.
164
+ #: () -> bool
165
+ def none?
166
+ operator, parts = @predicate
167
+ operator == :or && parts.empty?
168
+ end
169
+
161
170
  # The members among records that are each the owner's by key: those that
162
171
  # meet the conditions, then ranked.
163
172
  #: (Array[untyped]) -> Array[untyped]
@@ -181,10 +190,18 @@ module PaperTrailDiff
181
190
  eq: ->(value, expected) { expected.nil? || !value.nil? ? value == expected : nil },
182
191
  not_eq: ->(value, expected) { expected.nil? || !value.nil? ? value != expected : nil },
183
192
  in: ->(value, expected) { expected.include?(value) unless value.nil? },
184
- not_in: ->(value, expected) { !expected.include?(value) unless value.nil? }
193
+ not_in: ->(value, expected) { !expected.include?(value) unless value.nil? },
194
+ gt: ->(value, expected) { value > expected unless value.nil? },
195
+ gteq: ->(value, expected) { value >= expected unless value.nil? },
196
+ lt: ->(value, expected) { value < expected unless value.nil? },
197
+ lteq: ->(value, expected) { value <= expected unless value.nil? }
185
198
  }.freeze
186
199
  private_constant :COMPARISONS
187
200
 
201
+ # Comparisons that order values, which read them as ScopeRanking sorts.
202
+ ORDERED = %i[gt gteq lt lteq].freeze
203
+ private_constant :ORDERED
204
+
188
205
  private
189
206
 
190
207
  # @rbs @model_class: untyped
@@ -199,7 +216,7 @@ module PaperTrailDiff
199
216
  when :and then all(first.map { |part| evaluate(part, attributes) })
200
217
  when :or then any(first.map { |part| evaluate(part, attributes) })
201
218
  when :not then negate(evaluate(first, attributes))
202
- else COMPARISONS.fetch(operator).call(stored(first, attributes), second)
219
+ else COMPARISONS.fetch(operator).call(stored(operator, first, attributes), second)
203
220
  end
204
221
  end
205
222
 
@@ -224,10 +241,15 @@ module PaperTrailDiff
224
241
  !value unless value.nil?
225
242
  end
226
243
 
227
- # The form the database holds, as the scope's own values were cast.
228
- #: (String, Hash[String, untyped]) -> untyped
229
- def stored(name, attributes)
230
- @model_class.type_for_attribute(name).serialize(attributes[name])
244
+ # The form the database holds, as the scope's own values were cast. An
245
+ # order reads the value the database sorts by instead: SQL Server holds a
246
+ # time or date in a wrapper that only compares for equality.
247
+ #: (Symbol, String, Hash[String, untyped]) -> untyped
248
+ def stored(operator, name, attributes)
249
+ value = attributes[name]
250
+ return ScopeRanking.sort_value(@model_class, name, value) if ORDERED.include?(operator)
251
+
252
+ @model_class.type_for_attribute(name).serialize(value)
231
253
  end
232
254
 
233
255
  # Builds each reflection's condition once per target class.
@@ -293,10 +315,51 @@ module PaperTrailDiff
293
315
  when 'Arel::Nodes::HomogeneousIn' then homogeneous_in(node)
294
316
  when 'Arel::Nodes::In' then list(:in, node.left, values(node.right))
295
317
  when 'Arel::Nodes::NotIn' then list(:not_in, node.left, values(node.right))
296
- else raise Unreadable
318
+ else range(node)
297
319
  end
298
320
  end
299
321
 
322
+ RANGES = { 'Arel::Nodes::GreaterThan' => :gt, 'Arel::Nodes::GreaterThanOrEqual' => :gteq,
323
+ 'Arel::Nodes::LessThan' => :lt, 'Arel::Nodes::LessThanOrEqual' => :lteq }.freeze
324
+ private_constant :RANGES
325
+
326
+ # A range, as `where(created_at: 1.day.ago..)` writes it, on a column
327
+ # whose values sort in Ruby as the database sorts them.
328
+ #: (untyped) -> Array[untyped]
329
+ def range(node)
330
+ name = node.class.name
331
+ return between(node) if name == 'Arel::Nodes::Between'
332
+
333
+ operator = RANGES[name] or raise Unreadable
334
+ bound(operator, node.left, node.right)
335
+ end
336
+
337
+ #: (untyped) -> Array[untyped]
338
+ def between(node)
339
+ low, high = node.right.children
340
+ [:and, [bound(:gteq, node.left, low), bound(:lteq, node.left, high)]]
341
+ end
342
+
343
+ #: (Symbol, untyped, untyped) -> Array[untyped]
344
+ def bound(operator, attribute, node)
345
+ name = column(attribute, null_test: true)
346
+ boolean = :boolean.equal?(@model_class.type_for_attribute(name).type)
347
+ raise Unreadable unless ScopeRanking.orderable?(@model_class, name) && !boolean
348
+
349
+ expected = value(node)
350
+ raise Unreadable if expected.nil?
351
+
352
+ [operator, name, sort_value(name, expected)]
353
+ end
354
+
355
+ # A bound in the form the database holds, read back as the value the
356
+ # database sorts by. Reading it back unwraps what an adapter wraps.
357
+ #: (String, untyped) -> untyped
358
+ def sort_value(name, stored)
359
+ read = @model_class.type_for_attribute(name).deserialize(stored)
360
+ ScopeRanking.sort_value(@model_class, name, read)
361
+ end
362
+
300
363
  # Whether a value is NULL compares alike on every type.
301
364
  #: (Symbol, untyped) -> Array[untyped]
302
365
  def binary(operator, node)
@@ -325,12 +388,9 @@ module PaperTrailDiff
325
388
  # type compares alike.
326
389
  #: (untyped, ?null_test: bool) -> String
327
390
  def column(attribute, null_test: false)
328
- raise Unreadable unless ATTRIBUTE.eql?(attribute.class.name)
329
-
330
- table = attribute.relation
331
- raise Unreadable unless table.name == @model_class.table_name && table.table_alias.nil?
332
-
333
- name = attribute.name
391
+ # Nil for anything but a column of the model's own table, which finds
392
+ # no column below.
393
+ name = ScopeRanking.own_column(attribute, @model_class) #: String
334
394
  column = @model_class.columns_hash[name]
335
395
  raise Unreadable unless column && (null_test || comparable?(name, column))
336
396
 
@@ -47,7 +47,7 @@ module PaperTrailDiff
47
47
  # Returns nil when the ranking cannot be read exactly.
48
48
  #: (untyped, untyped, untyped) -> ScopeRanking?
49
49
  def self.build(relation, reflection, model_class)
50
- return unless own?(reflection) && plain_offset?(relation)
50
+ return unless own?(reflection)
51
51
 
52
52
  keys = keys(relation.order_values, model_class)
53
53
  return unless keys
@@ -55,7 +55,7 @@ module PaperTrailDiff
55
55
  nulls_last = NULLS_LAST[model_class.connection_db_config.adapter]
56
56
  return if nulls_last.nil?
57
57
 
58
- new(model_class, keys, nulls_last, relation.limit_value, relation.offset_value)
58
+ new(model_class, keys, nulls_last, Support.limit(relation), Support.offset(relation))
59
59
  end
60
60
 
61
61
  #: (untyped) -> bool
@@ -64,14 +64,6 @@ module PaperTrailDiff
64
64
  end
65
65
  private_class_method :own?
66
66
 
67
- # Active Record casts a limit to an integer but keeps an offset as given,
68
- # which may be a String or SQL.
69
- #: (untyped) -> bool
70
- def self.plain_offset?(relation)
71
- !relation.offset_value.is_a?(String)
72
- end
73
- private_class_method :plain_offset?
74
-
75
67
  # The order's keys up to the primary key, which makes it total. Keys
76
68
  # after it never decide anything.
77
69
  #: (Array[untyped], untyped) -> Array[[String, bool]]?
@@ -95,18 +87,22 @@ module PaperTrailDiff
95
87
  def self.column(node, model_class)
96
88
  return unless DIRECTIONS.key?(node.class.name)
97
89
 
98
- attribute = node.expr
90
+ name = own_column(node.expr, model_class)
91
+ name if orderable?(model_class, name)
92
+ end
93
+ private_class_method :column
94
+
95
+ # The name an Arel attribute gives a column of the model's own table, not
96
+ # of another table or an alias of its own; nil for anything else.
97
+ #: (untyped, untyped) -> String?
98
+ def self.own_column(attribute, model_class)
99
99
  return unless ATTRIBUTE.eql?(attribute.class.name)
100
100
 
101
101
  table = attribute.relation
102
- return unless table.name == model_class.table_name && table.table_alias.nil?
103
-
104
- name = attribute.name
105
- name if orderable?(model_class, name)
102
+ attribute.name if table.name == model_class.table_name && table.table_alias.nil?
106
103
  end
107
- private_class_method :column
108
104
 
109
- #: (untyped, String) -> bool
105
+ #: (untyped, String?) -> bool
110
106
  def self.orderable?(model_class, name)
111
107
  return false unless model_class.columns_hash.key?(name)
112
108
 
@@ -115,7 +111,16 @@ module PaperTrailDiff
115
111
  ORDER_TYPES.intersect?(kinds) ||
116
112
  (kinds.include?(DATETIME_TYPE) && exact_time?(model_class, type))
117
113
  end
118
- private_class_method :orderable?
114
+
115
+ # The value the database sorts by, as the column's type casts it. An enum
116
+ # sorts by the integer it stores; other types are compared cast, since an
117
+ # adapter may serialize a time or date as a wrapper, as SQL Server does.
118
+ #: (untyped, String, untyped) -> untyped
119
+ def self.sort_value(model_class, name, value)
120
+ type = model_class.type_for_attribute(name)
121
+ cast = type.cast(value)
122
+ ENUM_TYPE.eql?(type.class.name) ? type.serialize(cast) : cast
123
+ end
119
124
 
120
125
  # The type of the value a column stores, under an enum or time zone wrapper.
121
126
  #: (untyped) -> untyped
@@ -137,7 +142,7 @@ module PaperTrailDiff
137
142
  end
138
143
  private_class_method :exact_time?
139
144
 
140
- #: (untyped, Array[[String, bool]], bool, Integer?, Integer?) -> void
145
+ #: (untyped, Array[[String, bool]], bool, Integer?, Integer) -> void
141
146
  def initialize(model_class, keys, nulls_last, limit, offset)
142
147
  @model_class = model_class
143
148
  @keys = keys
@@ -150,10 +155,8 @@ module PaperTrailDiff
150
155
  # The members among records that met the scope's conditions, in order.
151
156
  #: (Array[untyped]) -> Array[untyped]
152
157
  def call(records)
153
- offset = @offset
154
158
  limit = @limit
155
- ranked = records.sort_by { |record| sort_key(record.attributes) }
156
- ranked = ranked.drop(offset) if offset
159
+ ranked = records.sort_by { |record| sort_key(record.attributes) }.drop(@offset)
157
160
  limit ? ranked.first(limit) : ranked
158
161
  end
159
162
 
@@ -163,7 +166,7 @@ module PaperTrailDiff
163
166
  # @rbs @keys: Array[[String, bool]]
164
167
  # @rbs @nulls_last: bool
165
168
  # @rbs @limit: Integer?
166
- # @rbs @offset: Integer?
169
+ # @rbs @offset: Integer
167
170
 
168
171
  # Keys compare in turn, and the primary key always decides. A descending
169
172
  # key negates its places, which also moves NULL to the other end, as each
@@ -171,7 +174,7 @@ module PaperTrailDiff
171
174
  #: (Hash[String, untyped]) -> Array[Array[Numeric]]
172
175
  def sort_key(attributes)
173
176
  @keys.map do |name, descending|
174
- place = place(stored(name, attributes))
177
+ place = place(ScopeRanking.sort_value(@model_class, name, attributes[name]))
175
178
  descending ? place.map(&:-@) : place
176
179
  end
177
180
  end
@@ -192,15 +195,5 @@ module PaperTrailDiff
192
195
  value = value.jd if value.respond_to?(:jd)
193
196
  value.to_r
194
197
  end
195
-
196
- # The value the database sorts by, as the key's type casts it. An enum
197
- # sorts by the integer it stores; other types are compared cast, since an
198
- # adapter may serialize a time or date as a wrapper, as SQL Server does.
199
- #: (String, Hash[String, untyped]) -> untyped
200
- def stored(name, attributes)
201
- type = @model_class.type_for_attribute(name)
202
- value = type.cast(attributes[name])
203
- ENUM_TYPE.eql?(type.class.name) ? type.serialize(value) : value
204
- end
205
198
  end
206
199
  end
@@ -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?) -> 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
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,9 +17,11 @@ 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
20
+ activity_tree: activity_tree, version_scope: version_scope,
21
+ traversal: traversal
21
22
  )
22
- @deleted_filter = DeletedRootFilter.new(scope.all) if include_deleted
23
+ @deleted_filter = deleted_filter(scope, include_deleted)
24
+ @include_deleted = include_deleted
23
25
  @limit = limit
24
26
  @analyzer = analyzer
25
27
  @deleted_analyzer = deleted_analyzer
@@ -28,10 +30,9 @@ module PaperTrailDiff
28
30
  #: () -> ScopedAnalysis
29
31
  def call
30
32
  selection = @selection.call
31
- deleted_filter = @deleted_filter
32
- return analysis(selection, selection.unreachable, {}) unless deleted_filter
33
+ unreachable = @deleted_filter&.call(selection.unreachable) || selection.unreachable
34
+ return analysis(selection, unreachable, {}) unless @include_deleted
33
35
 
34
- unreachable = deleted_filter.call(selection.unreachable)
35
36
  if selection.records.length + unreachable.length > @limit
36
37
  raise BatchLimitExceededError, 'include_deleted: live and missing roots exceed limit:'
37
38
  end
@@ -41,6 +42,15 @@ module PaperTrailDiff
41
42
 
42
43
  private
43
44
 
45
+ # Without the option, the deleted roots are still tested when the
46
+ # relation can be read, so that another selection's are not listed.
47
+ #: (untyped, bool) -> DeletedRootFilter?
48
+ def deleted_filter(scope, include_deleted)
49
+ return DeletedRootFilter.new(scope.all) if include_deleted
50
+
51
+ DeletedRootFilter.readable(scope.all)
52
+ end
53
+
44
54
  #: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
45
55
  def analysis(selection, unreachable, deleted)
46
56
  ScopedAnalysis.new(analyses: @analyzer.call(selection.records), roots: selection.records,
@@ -49,6 +59,7 @@ module PaperTrailDiff
49
59
 
50
60
  # @rbs @selection: ScopedRootSelection
51
61
  # @rbs @deleted_filter: DeletedRootFilter?
62
+ # @rbs @include_deleted: bool
52
63
  # @rbs @limit: Integer
53
64
  # @rbs @analyzer: untyped
54
65
  # @rbs @deleted_analyzer: untyped
@@ -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,23 +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.
49
- #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> 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
50
53
  def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
51
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil)
54
+ max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil,
55
+ version_scope: nil, traversal: nil)
52
56
  @scope = normalize_scope(scope)
53
57
  reject_unversioned!
54
58
  @time_range = time_range
59
+ @path_types = traversal ? traversal.path_types(model) : [] #: Array[String]
60
+ @version_scope = VersionScopeFilter.validated(version_scope)
55
61
  @limit = validate_limit(limit)
56
- @related = if activity_tree
57
- AssociationActivitySelection.new(model, tree: activity_tree,
58
- time_range: time_range)
59
- end
60
- @historical_filter = unless historical_filter.nil?
61
- HistoricalFilter.new(base_class, predicate: historical_filter,
62
- time_range: time_range, limit: @limit,
63
- max_versions: max_filter_versions)
64
- 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)
65
66
  end
66
67
 
67
68
  #: () -> Result
@@ -80,6 +81,8 @@ module PaperTrailDiff
80
81
  # @rbs @limit: Integer
81
82
  # @rbs @historical_filter: untyped
82
83
  # @rbs @related: AssociationActivitySelection?
84
+ # @rbs @version_scope: untyped
85
+ # @rbs @path_types: Array[String]
83
86
 
84
87
  # Leaves the candidate set in the database. Plucking every root changed in
85
88
  # the window would cost memory and a statement proportional to all activity
@@ -117,13 +120,22 @@ module PaperTrailDiff
117
120
  live = ids_in(base_class.unscoped, candidates)
118
121
  missing = candidates - live
119
122
  if (filter = @historical_filter)
120
- live = filter.call(ids_in(@scope.except(:order, :limit, :offset), live).uniq)
123
+ live = filter.call(relation_members(live))
121
124
  missing = filter.call(missing, counted: false)
122
125
  end
123
126
  Result.new(records: selected_records([live]),
124
127
  unreachable: missing.sort.map { |id| identity(id) }.freeze)
125
128
  end
126
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
+
127
139
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
128
140
  # rejects an integer key against a string item_id outright. A composite
129
141
  # key names no single attribute, so it has no type and never matches.
@@ -150,11 +162,24 @@ module PaperTrailDiff
150
162
  window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
151
163
  end
152
164
 
165
+ # 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.
153
169
  #: () -> untyped
154
170
  def window_versions
155
- relation = VersionQuery.for_model(model)
156
- range = @time_range
157
- range ? range.scope(relation) : relation
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))
158
183
  end
159
184
 
160
185
  # Accepts a model class as readily as a relation: `Article` and
@@ -195,7 +220,7 @@ module PaperTrailDiff
195
220
 
196
221
  #: (untyped, Array[String]) -> Array[String]
197
222
  def ids_in(relation, candidates)
198
- candidates.each_slice(PAGE_SIZE).flat_map do |slice|
223
+ candidates.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
199
224
  relation.where(primary_key => slice).pluck(primary_key).map(&:to_s)
200
225
  end
201
226
  end
@@ -214,18 +239,19 @@ module PaperTrailDiff
214
239
  page = record_page(relation, consumed)
215
240
  page.each { |record| records[record.id] ||= record }
216
241
  reject_oversized!(records.length)
217
- break if page.length < PAGE_SIZE
242
+ break if page.length < page_size
218
243
 
219
244
  consumed += page.length
220
245
  end
221
246
  records.values.freeze
222
247
  end
223
248
 
249
+ # Pages are read by offset, so under a total order.
224
250
  #: (Array[untyped]) -> untyped
225
251
  def candidate_relation(candidates)
226
252
  candidates.map do |ids|
227
253
  conditions = { primary_key => ids } #: Hash[untyped, untyped]
228
- ordered_scope.where(conditions)
254
+ TotalOrder.apply(@scope).where(conditions)
229
255
  end.reduce(:or)
230
256
  end
231
257
 
@@ -234,22 +260,26 @@ module PaperTrailDiff
234
260
  count = page_limit(consumed)
235
261
  return [] if count.zero?
236
262
 
237
- relation.offset((@scope.offset_value || 0) + consumed).limit(count)
238
- end
239
-
240
- # Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
241
- # even when the extra ordering would only have served as a tie-breaker.
242
- #: () -> untyped
243
- def ordered_scope
244
- return @scope unless @scope.order_values.empty?
245
-
246
- @scope.order(primary_key => :asc)
263
+ relation.offset(Support.offset(@scope) + consumed).limit(count)
247
264
  end
248
265
 
249
266
  #: (Integer) -> Integer
250
267
  def page_limit(consumed)
251
- remaining = @scope.limit_value
252
- [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)
253
283
  end
254
284
 
255
285
  #: (Integer) -> void
@@ -261,14 +291,10 @@ module PaperTrailDiff
261
291
  'relation, or raise limit: to the page size you intend to analyze'
262
292
  end
263
293
 
294
+ # Keyed as Endpoint.identity keys the record, which the analyses use.
264
295
  #: (String) -> Array[String]
265
296
  def identity(id)
266
- [item_type, id].freeze
267
- end
268
-
269
- #: () -> String
270
- def item_type
271
- base_class.name
297
+ Support.record_identity(model, id).freeze
272
298
  end
273
299
 
274
300
  # A relation delegates class methods to its model, so every mutation here,