paper_trail_diff 0.16.0 → 0.17.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +581 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +19 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  44. data/lib/paper_trail_diff/change_attribution.rb +329 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +197 -45
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +41 -19
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +192 -91
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +27 -16
  105. data/lib/paper_trail_diff/version_boundary.rb +37 -21
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +194 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +114 -14
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +10 -9
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +28 -6
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -3,45 +3,48 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Reconstructs and caches immutable historical snapshots for one adapter
6
- # configuration. It keeps the histories batches prepare, by root version;
7
- # one prepared for a single root goes back to the caller, who passes it to
8
- # every read for that root.
6
+ # configuration. It keeps the histories batches prepare, by root and by root
7
+ # version; one prepared for a single root goes back to the caller, who
8
+ # passes it to every read for that root.
9
9
  class HistoricalSnapshotStore
10
- #: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
11
- def initialize(tree:, traversal:, normalizer:, preparer:)
12
- @tree = tree
10
+ #: (traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
11
+ def initialize(traversal:, normalizer:, preparer:)
12
+ @tree = traversal.tree
13
13
  @traversal = traversal
14
14
  @normalizer = normalizer
15
15
  @preparer = preparer
16
16
  @prepared_snapshotter = PreparedSnapshotBuilder.new(traversal)
17
- @live_graph_collector = LiveGraphCollector.new(tree: tree, traversal: traversal)
17
+ @live_graph_collector = LiveGraphCollector.new(traversal)
18
18
  @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
19
19
  @prepared_histories = {} #: Hash[Array[untyped], PreparedHistory]
20
+ @batched_roots = {} #: Hash[identity, PreparedHistory]
20
21
  @live_roots = {} #: Hash[identity, untyped]
22
+ @live_states = {} #: Hash[identity, PreparedRecordState]
21
23
  end
22
24
 
25
+ # A `start_at` is a window's (see PreparedHistoryLoader); a range of
26
+ # versions starts at its first.
23
27
  #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
24
- def prepare(
25
- record,
26
- root_versions,
27
- start_at: root_versions.first.created_at,
28
- end_at: root_versions.last.created_at
29
- )
28
+ def prepare(record, root_versions, start_at: nil, end_at: root_versions.last.created_at)
30
29
  return if @tree.empty?
31
30
 
32
- # A batched preparation already covers these roots.
33
- batched = root_versions.find { |version| @prepared_histories.key?(context_key(version)) }
34
- return @prepared_histories.fetch(context_key(batched)) if batched
31
+ # A batch prepared this root with the others, including a root with no
32
+ # version in the window that closes on its current state.
33
+ batched = @batched_roots[Endpoint.identity(record)]
34
+ return batched if batched
35
35
 
36
36
  PreparedHistoryLoader.new(
37
- record, root_ids: [record.id], root_versions: root_versions, start_at: start_at,
38
- end_at: end_at, tree: @tree, traversal: @traversal, live_records: []
37
+ record, root_ids: [record.id], root_versions: root_versions,
38
+ start_at: start_at || root_versions.first.created_at, end_at: end_at, tree: @tree,
39
+ traversal: @traversal, live_records: [], window: !start_at.nil?
39
40
  ).call
40
41
  end
41
42
 
43
+ # A `start_at` is a window's, as for `prepare`. A window's roots may have
44
+ # no version in it, when only their descendants changed there.
42
45
  #: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
43
46
  def prepare_batch(records, root_versions, start_at: nil, end_at: nil)
44
- return if @tree.empty? || records.empty? || root_versions.empty?
47
+ return if @tree.empty? || records.empty? || (root_versions.empty? && start_at.nil?)
45
48
 
46
49
  Instrumentation.instrument('prepare_history', batch_payload(records, root_versions)) do
47
50
  register_batch(records, root_versions, start_at: start_at, end_at: end_at)
@@ -89,6 +92,16 @@ module PaperTrailDiff
89
92
  history: history)
90
93
  end
91
94
 
95
+ # The state a snapshot of the root at this endpoint starts from when built
96
+ # from prepared history: the one a version stored, or the live row's.
97
+ # Nil where a version's is read another way.
98
+ #: (untyped) -> PreparedRecordState?
99
+ def root_state(root_endpoint)
100
+ return @prepared_snapshotter.state(root_endpoint) if Endpoint.version?(root_endpoint)
101
+
102
+ live_state(root_endpoint)
103
+ end
104
+
92
105
  #: (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
93
106
  def association_reader(context_version, habtm_version:, history: nil)
94
107
  fallback = HistoricalAssociationReifier.new(
@@ -116,17 +129,14 @@ module PaperTrailDiff
116
129
  # @rbs @live_graph_collector: LiveGraphCollector
117
130
  # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]
118
131
  # @rbs @prepared_histories: Hash[Array[untyped], PreparedHistory]
132
+ # @rbs @batched_roots: Hash[identity, PreparedHistory]
119
133
  # @rbs @live_roots: Hash[identity, untyped]
134
+ # @rbs @live_states: Hash[identity, PreparedRecordState]
120
135
 
121
136
  # A batch's history for the version wins over the one a caller passes.
122
137
  #: (untyped, PreparedHistory?) -> PreparedHistory?
123
138
  def history_for(context_endpoint, history)
124
- @prepared_histories[context_key(context_endpoint)] || history
125
- end
126
-
127
- #: (untyped) -> Array[untyped]
128
- def context_key(endpoint)
129
- [endpoint.class.name, endpoint.id]
139
+ @prepared_histories[Support.row_key(context_endpoint)] || history
130
140
  end
131
141
 
132
142
  #: (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
@@ -146,9 +156,17 @@ module PaperTrailDiff
146
156
  end_at: end_at || root_versions.map(&:created_at).max,
147
157
  tree: @tree,
148
158
  traversal: @traversal,
149
- live_records: live_records
159
+ live_records: live_records,
160
+ window: !start_at.nil?
150
161
  ).call
151
- root_versions.each { |version| @prepared_histories[context_key(version)] = history }
162
+ register(history, records, root_versions)
163
+ end
164
+
165
+ # Snapshot reads find the history by root version, and `prepare` by root.
166
+ #: (PreparedHistory, Array[untyped], Array[untyped]) -> void
167
+ def register(history, records, root_versions)
168
+ root_versions.each { |version| @prepared_histories[Support.row_key(version)] = history }
169
+ records.each { |record| @batched_roots[Endpoint.identity(record)] = history }
152
170
  end
153
171
 
154
172
  #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
@@ -161,30 +179,54 @@ module PaperTrailDiff
161
179
  )
162
180
  return snapshot if handled
163
181
 
164
- record = root_version.reify(dup: true)
182
+ record = Support.reify(root_version, dup: true)
165
183
  normalize(record, context_version, tree: tree, normalizer: normalizer,
166
184
  habtm_version: root_version, history: history)
167
185
  end
168
186
 
187
+ # Read from prepared history where it can be, as a version is, without
188
+ # instantiating the root's members. Only the fallback, which writes the
189
+ # members it rebuilds onto the root, needs a record of its own.
169
190
  #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
170
191
  def snapshot_from_live_root(root_record, context_version, tree:, normalizer:, history:)
171
- record = live_root(root_record)
172
- @preparer.call(record.class, historical: true)
173
- normalize(record, context_version, tree: tree, normalizer: normalizer,
174
- habtm_version: context_version, history: history)
192
+ state = live_state(root_record)
193
+ @preparer.call(state.model_class, historical: true)
194
+ handled, snapshot = @prepared_snapshotter.live(
195
+ state, context_version, tree: tree, normalizer: normalizer, history: history
196
+ )
197
+ return snapshot if handled
198
+
199
+ normalize(live_root(root_record), context_version, tree: tree, normalizer: normalizer,
200
+ habtm_version: context_version,
201
+ history: history)
202
+ end
203
+
204
+ # The state of the root's row, read once for the call: every snapshot
205
+ # that starts from the row starts from the same state. Reading it writes
206
+ # nothing to the row, so it is read from the loaded record itself, whose
207
+ # columns the current snapshot reads too.
208
+ #: (untyped) -> PreparedRecordState
209
+ def live_state(root_record)
210
+ identity = Endpoint.identity(root_record)
211
+ @live_states[identity] ||= PreparedRecordState.new(loaded_root(root_record, identity))
175
212
  end
176
213
 
177
214
  # Rebuilding a version's associations writes them onto the record, so each
178
- # snapshot gets its own copy of a batch's loaded row, built from the row's
179
- # stored values without a query.
215
+ # snapshot that does gets its own copy of the root's row, built from the
216
+ # row's stored values without a query.
180
217
  #: (untyped) -> untyped
181
218
  def live_root(root_record)
182
- loaded = @live_roots[Endpoint.identity(root_record)]
183
- return Endpoint.reload_record(root_record) unless loaded
184
-
219
+ loaded = loaded_root(root_record, Endpoint.identity(root_record))
185
220
  loaded.class.instantiate(loaded.attributes_before_type_cast)
186
221
  end
187
222
 
223
+ # A batch loaded the row already; otherwise it is read once, so every
224
+ # snapshot of the call starts from the same row.
225
+ #: (untyped, identity) -> untyped
226
+ def loaded_root(root_record, identity)
227
+ @live_roots[identity] ||= Endpoint.reload_record(root_record)
228
+ end
229
+
188
230
  #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
189
231
  def normalize(record, context_version, tree:, normalizer:, habtm_version:, history:) # rubocop:disable Metrics/ParameterLists
190
232
  reifier = association_reader(context_version, habtm_version: habtm_version, history: history)
@@ -196,7 +238,7 @@ module PaperTrailDiff
196
238
 
197
239
  #: (untyped, untyped) -> Array[untyped]
198
240
  def snapshot_key(root_endpoint, context_endpoint)
199
- context_key(root_endpoint) + context_key(context_endpoint)
241
+ Support.row_key(root_endpoint) + Support.row_key(context_endpoint)
200
242
  end
201
243
  end
202
244
  end
@@ -26,13 +26,5 @@ module PaperTrailDiff
26
26
  instrument(event, payload) { nil }
27
27
  nil
28
28
  end
29
-
30
- #: (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
31
- def comparison_payload(association_paths:, reload_live_endpoints:)
32
- {
33
- association_paths: association_paths,
34
- reload_live_endpoints: reload_live_endpoints
35
- }
36
- end
37
29
  end
38
30
  end
@@ -25,20 +25,26 @@ module PaperTrailDiff
25
25
 
26
26
  # @rbs @tree: AssociationTree
27
27
 
28
+ # Each statement reads 500 records.
28
29
  #: (untyped, Array[untyped]) -> Array[untyped]
29
30
  def load_group(model_class, records)
30
- relation = model_class.unscoped.where(model_class.primary_key => records.map(&:id).uniq)
31
- loaded = relation.to_a
31
+ loaded = records.map(&:id).uniq.each_slice(Support::IDS_PER_STATEMENT).flat_map do |ids|
32
+ model_class.unscoped.where(model_class.primary_key => ids).to_a
33
+ end
32
34
  preload_tree(loaded, @tree)
33
35
  loaded
34
36
  end
35
37
 
38
+ # Active Record preloads an association of all the records it is given in
39
+ # one statement, so they are given 500 at a time.
36
40
  #: (Array[untyped], AssociationTree) -> void
37
41
  def preload_tree(records, tree)
38
42
  return if records.empty? || tree.empty?
39
43
 
40
- records.group_by(&:class).each do |model_class, grouped_records|
41
- preload_model_tree(model_class, grouped_records, tree)
44
+ records.each_slice(Support::IDS_PER_STATEMENT) do |slice|
45
+ slice.group_by(&:class).each do |model_class, grouped_records|
46
+ preload_model_tree(model_class, grouped_records, tree)
47
+ end
42
48
  end
43
49
  end
44
50
 
@@ -115,9 +121,7 @@ module PaperTrailDiff
115
121
 
116
122
  #: (Array[untyped]) -> Array[untyped]
117
123
  def unique_records(records)
118
- records.compact.uniq do |record|
119
- [record.class.base_class.name.to_s, record.id.to_s]
120
- end
124
+ records.compact.uniq { |record| Support.record_identity(record.class, record.id) }
121
125
  end
122
126
 
123
127
  #: (Array[untyped], Hash[identity, untyped]) -> void
@@ -2,27 +2,12 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Selects safe reload or validated caller-owned loading for current endpoints.
5
+ # Reloads the current records a call compares with, with their requested
6
+ # associations, once per call.
6
7
  class LiveEndpointProvider
7
- attr_reader :reload #: bool
8
- attr_reader :comparison_payload #: Hash[Symbol, untyped]
9
-
10
- #: (tree: AssociationTree, traversal: AssociationTraversal, reload: bool) -> void
11
- def initialize(tree:, traversal:, reload:)
12
- unless [true, false].include?(reload)
13
- raise ConfigurationError, 'reload_live_endpoints: must be true or false'
14
- end
15
-
16
- @reload = reload
17
- @comparison_payload = Instrumentation.comparison_payload(
18
- association_paths: tree.paths,
19
- reload_live_endpoints: reload
20
- ).freeze
21
- @loader = if reload
22
- LiveEndpointBatchLoader.new(tree: tree)
23
- else
24
- PreloadedEndpointBatchLoader.new(tree: tree, traversal: traversal)
25
- end
8
+ #: (tree: AssociationTree) -> void
9
+ def initialize(tree:)
10
+ @loader = LiveEndpointBatchLoader.new(tree: tree)
26
11
  @loaded = {} #: Hash[identity, untyped]
27
12
  end
28
13
 
@@ -44,7 +29,7 @@ module PaperTrailDiff
44
29
 
45
30
  private
46
31
 
47
- # @rbs @loader: untyped
32
+ # @rbs @loader: LiveEndpointBatchLoader
48
33
  # @rbs @loaded: Hash[identity, untyped]
49
34
 
50
35
  #: (Array[untyped]) -> Hash[identity, untyped]
@@ -59,8 +44,7 @@ module PaperTrailDiff
59
44
  def payload(records)
60
45
  {
61
46
  endpoint_count: records.length,
62
- model_types: records.map { |record| record.class.base_class.name.to_s }.uniq.sort.freeze,
63
- reload_live_endpoints: reload
47
+ model_types: records.map { |record| record.class.base_class.name.to_s }.uniq.sort.freeze
64
48
  }
65
49
  end
66
50
  end
@@ -4,9 +4,9 @@
4
4
  module PaperTrailDiff
5
5
  # Flattens an already-preloaded, explicitly bounded live association graph.
6
6
  class LiveGraphCollector
7
- #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
8
- def initialize(tree:, traversal:)
9
- @tree = tree
7
+ #: (AssociationTraversal) -> void
8
+ def initialize(traversal)
9
+ @tree = traversal.tree
10
10
  @traversal = traversal
11
11
  end
12
12
 
@@ -25,6 +25,10 @@ module PaperTrailDiff
25
25
  # An absent key is not a null one. `{"a": null}` and `{}` mean different
26
26
  # things in JSON and an audit trail that conflated them would be lying about
27
27
  # one of them, so absence is its own value rather than nil.
28
+ #
29
+ # A key is its name: `:a` and `"a"` are one key at any depth, inside arrays
30
+ # too, because a hash built in Ruby and one read back from JSON key the same
31
+ # field differently. Values are reported as they were given.
28
32
  class NestedComparator
29
33
  # Stands in for a key that was not there at all.
30
34
  class Absent
@@ -43,6 +47,33 @@ module PaperTrailDiff
43
47
  new(from_value, to_value).call
44
48
  end
45
49
 
50
+ # The value as it is compared: every Hash key read as a string, at any
51
+ # depth and inside arrays, and everything else as it is.
52
+ #: (untyped) -> untyped
53
+ def self.comparable(value)
54
+ case value
55
+ when Hash then string_keyed(value) { |item| comparable(item) }
56
+ when Array then value.map { |item| comparable(item) }
57
+ else value
58
+ end
59
+ end
60
+
61
+ # The hash keyed by name, each value as the block returns it. Two keys
62
+ # with one name, such as `:a` and `"a"`, cannot both be kept.
63
+ #: (Hash[untyped, untyped]) { (untyped) -> untyped } -> Hash[String, untyped]
64
+ def self.string_keyed(hash)
65
+ normalized = {} #: Hash[String, untyped]
66
+ hash.each do |key, value|
67
+ name = key.to_s
68
+ if normalized.key?(name)
69
+ raise AmbiguousNestedKeyError, "duplicate nested key after normalization: #{name.inspect}"
70
+ end
71
+
72
+ normalized[name] = yield(value)
73
+ end
74
+ normalized
75
+ end
76
+
46
77
  #: (untyped, untyped) -> void
47
78
  def initialize(from_value, to_value)
48
79
  @from_value = from_value
@@ -61,7 +92,8 @@ module PaperTrailDiff
61
92
  walk(from, to, [], changes)
62
93
  elsif from.is_a?(Array) && to.is_a?(Array)
63
94
  whole = [] #: Array[String]
64
- changes[whole.freeze] = change_for(from, to) if from != to
95
+ change = change_for(from, to)
96
+ changes[whole.freeze] = change if change
65
97
  end
66
98
  changes.freeze
67
99
  end
@@ -103,34 +135,29 @@ module PaperTrailDiff
103
135
  if from_item.is_a?(Hash) && to_item.is_a?(Hash)
104
136
  walk(from_item, to_item, here, changes)
105
137
  else
106
- changes[here] = change_for(from_item, to_item)
138
+ change = change_for(from_item, to_item)
139
+ changes[here] = change if change
107
140
  end
108
141
  end
109
142
  end
110
143
 
111
144
  #: (Hash[untyped, untyped]) -> Hash[String, untyped]
112
145
  def normalize_keys(hash)
113
- normalized = {} #: Hash[String, untyped]
114
- hash.each do |key, value|
115
- name = key.to_s
116
- if normalized.key?(name)
117
- raise AmbiguousNestedKeyError, "duplicate nested key after normalization: #{name.inspect}"
118
- end
119
-
120
- normalized[name] = value
121
- end
122
- normalized
146
+ NestedComparator.string_keyed(hash, &:itself)
123
147
  end
124
148
 
125
- # Two arrays are a membership change; anything else is a change to the
126
- # value as a whole, including an array facing something that is not one.
127
- #: (untyped, untyped) -> nested_change
149
+ # Two arrays are a membership change, or none when they hold the same
150
+ # elements in the same order once keys are read as strings; anything else
151
+ # is a change to the value as a whole, including an array facing something
152
+ # that is not one.
153
+ #: (untyped, untyped) -> nested_change?
128
154
  def change_for(from_item, to_item)
129
- if from_item.is_a?(Array) && to_item.is_a?(Array)
130
- ArrayChange.new(from: from_item, to: to_item)
131
- else
132
- ValueChange.new(from: from_item, to: to_item)
155
+ unless from_item.is_a?(Array) && to_item.is_a?(Array)
156
+ return ValueChange.new(from: from_item, to: to_item)
133
157
  end
158
+
159
+ change = ArrayChange.new(from: from_item, to: to_item)
160
+ change unless change.empty?
134
161
  end
135
162
 
136
163
  # Sorted so a report reads the same twice. Both hashes are already keyed by