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
@@ -17,13 +17,6 @@ module PaperTrailDiff
17
17
 
18
18
  @version_class: untyped
19
19
 
20
- # Only quoting helpers are needed, so the connection is borrowed for the
21
- # duration of building the condition rather than checked out permanently,
22
- # which Active Record 7.2 and newer can deprecate. Active Record 7.1 has no
23
- # `with_connection` and reaches the same connection through the accessor.
24
- # : () { (untyped) -> String } -> String
25
- def with_connection: () { (untyped) -> String } -> String
26
-
27
20
  # : () -> String
28
21
  def candidate_condition: () -> String
29
22
 
@@ -8,8 +8,10 @@ module PaperTrailDiff
8
8
  # sequential ids in one version table; any other tie cannot be ordered, and
9
9
  # guessing would place a change on an arbitrary side of the boundary. A
10
10
  # bare instant has no position among same-time versions, so it keeps them.
11
- # : (untyped, untyped) -> bool
12
- def self?.at_or_after?: (untyped, untyped) -> bool
11
+ # `time` and `boundary_time` are when each was recorded, which a caller
12
+ # placing many versions against one boundary reads once.
13
+ # : (untyped, untyped, ?time: untyped, ?boundary_time: untyped) -> bool
14
+ def self.at_or_after?: (untyped, untyped, ?time: untyped, ?boundary_time: untyped) -> bool
13
15
 
14
16
  # A range starting at a version starts before that version's transaction,
15
17
  # as PT-AT reads associations there. A version saved earlier in the same
@@ -17,24 +19,31 @@ module PaperTrailDiff
17
19
  # version, can be recorded before the start, so the start moves back to
18
20
  # the earliest version of each root's first transaction in the range.
19
21
  # History loaded from the start alone would read that child after its
20
- # change.
22
+ # change. The transactions go 500 to a statement.
21
23
  # : (Array[untyped], untyped) -> untyped
22
- def self?.transaction_start: (Array[untyped], untyped) -> untyped
24
+ def self.transaction_start: (Array[untyped], untyped) -> untyped
23
25
 
24
26
  # The transaction of each root's first version at or after the start.
25
27
  # : (Array[untyped], untyped) -> Array[untyped]
26
- def self?.opening_transactions: (Array[untyped], untyped) -> Array[untyped]
28
+ def self.opening_transactions: (Array[untyped], untyped) -> Array[untyped]
27
29
 
28
30
  # A custom version class need not carry the column, and PaperTrail leaves
29
31
  # it nil outside a transaction. Both read as "no transaction here", which
30
32
  # groups with nothing.
31
33
  # : (untyped) -> untyped
32
- def self?.transaction_id: (untyped) -> untyped
34
+ def self.transaction_id: (untyped) -> untyped
35
+
36
+ # Answered once for each Active Record class (see Support.per_model).
37
+ # : (untyped) -> bool
38
+ def self.transactional?: (untyped) -> bool
33
39
 
40
+ # Answered once for each Active Record class, as `transactional?` is.
34
41
  # : (untyped) -> bool
35
- def self?.version_record?: (untyped) -> bool
42
+ def self.version_record?: (untyped) -> bool
36
43
 
44
+ # The same row of the same version table. A record or instant is never a
45
+ # version.
37
46
  # : (untyped, untyped) -> bool
38
- def self?.same_version?: (untyped, untyped) -> bool
47
+ def self.same_version?: (untyped, untyped) -> bool
39
48
  end
40
49
  end
@@ -7,31 +7,38 @@ module PaperTrailDiff
7
7
  # instant, and the timestamp comes first because ids need not follow time:
8
8
  # a UUID key does not.
9
9
  # : (untyped) -> untyped
10
- def self?.chronological: (untyped) -> untyped
10
+ def self.chronological: (untyped) -> untyped
11
11
 
12
12
  # Every version of a model's items. They are read from the version class
13
13
  # rather than through the model's versions association, whose scope may
14
14
  # leave some out: a history replayed without them credits their changes to
15
15
  # the next version kept.
16
16
  # : (untyped) -> untyped
17
- def self?.for_model: (untyped) -> untyped
17
+ def self.for_model: (untyped) -> untyped
18
18
 
19
19
  # The versions of the given items, read the same way.
20
20
  # : (untyped, untyped) -> untyped
21
- def self?.for_items: (untyped, untyped) -> untyped
21
+ def self.for_items: (untyped, untyped) -> untyped
22
22
 
23
23
  # Keeps each item's earliest version among those the block also accepts:
24
24
  # no other version of the same item that the block accepts is earlier. A
25
25
  # correlated NOT EXISTS stays portable where window functions are not.
26
26
  # : (untyped) ?{ (untyped) -> untyped } -> untyped
27
- def self?.no_earlier_version: (untyped) ?{ (untyped) -> untyped } -> untyped
27
+ def self.no_earlier_version: (untyped) ?{ (untyped) -> untyped } -> untyped
28
28
 
29
- # The same for either side of an instant: each item's earliest version
30
- # when the versions lie after it, and its latest when they lie before.
31
- # : (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
32
- def self?.no_nearer_version: (untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
29
+ # Whether a version exists that the block's condition accepts. The block
30
+ # is given the version table under a second name, beside `table`.
31
+ # : (untyped) { (untyped) -> untyped } -> untyped
32
+ def self.exists: (untyped) { (untyped) -> untyped } -> untyped
33
33
 
34
- # : (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
35
- def self?.nearer_version: (untyped, untyped, later: bool) ?{ (untyped) -> untyped } -> untyped
34
+ # : (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
35
+ def self.earlier_version: (untyped, untyped) ?{ (untyped) -> untyped } -> untyped
36
+
37
+ # The version table under a second name, for a subquery over it. Any name
38
+ # serves, and SQLite even accepts an empty one other databases refuse, so
39
+ # no spec can tell the mutations apart.
40
+ # mutant:disable
41
+ # : (untyped) -> untyped
42
+ def self.other_versions: (untyped) -> untyped
36
43
  end
37
44
  end
@@ -7,14 +7,14 @@ module PaperTrailDiff
7
7
  def initialize: (untyped, from: untyped, to: untyped, version_scope: untyped) -> void
8
8
 
9
9
  # Keep both reconstruction boundaries and the step pairs a filter implies.
10
- # : () -> RootVersionPlan
11
- def select_plan_for_range: () -> RootVersionPlan
10
+ # : (?whole: bool) -> RootVersionPlan
11
+ def select_plan_for_range: (?whole: bool) -> RootVersionPlan
12
12
 
13
13
  # : () -> untyped
14
14
  def validated_relation: () -> untyped
15
15
 
16
- # : (untyped) -> RootVersionPlan
17
- def select_plan_through_current: (untyped) -> RootVersionPlan
16
+ # : (untyped, ?whole: bool) -> RootVersionPlan
17
+ def select_plan_through_current: (untyped, ?whole: bool) -> RootVersionPlan
18
18
 
19
19
  private
20
20
 
@@ -26,11 +26,8 @@ module PaperTrailDiff
26
26
 
27
27
  @version_scope: untyped
28
28
 
29
- # : (untyped, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
30
- def select_plan: (untyped, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
31
-
32
- # : (Array[untyped]) -> Array[untyped]
33
- def ordered: (Array[untyped]) -> Array[untyped]
29
+ # : (untyped, whole: bool, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
30
+ def select_plan: (untyped, whole: bool, ?through: untyped, ?live_endpoint: untyped) -> RootVersionPlan
34
31
 
35
32
  # : (untyped, untyped, boundary: Symbol) -> void
36
33
  def validate_boundary!: (untyped, untyped, boundary: Symbol) -> void
@@ -8,6 +8,9 @@ module PaperTrailDiff
8
8
  # : (untyped, untyped, ?fallback_selected: bool) -> void
9
9
  def initialize: (untyped, untyped, ?fallback_selected: bool) -> void
10
10
 
11
+ # The read runs in a savepoint, so that a query that fails here leaves a
12
+ # snapshot transaction around it usable: PostgreSQL refuses every later
13
+ # statement of a transaction once one has failed.
11
14
  # : () -> Array[DiagnosticIssue]
12
15
  def call: () -> Array[DiagnosticIssue]
13
16
 
@@ -25,6 +28,19 @@ module PaperTrailDiff
25
28
  # : (Array[untyped]) -> DiagnosticIssue?
26
29
  def unorderable: (Array[untyped]) -> DiagnosticIssue?
27
30
 
31
+ # Versions are read in time order, and ids that count up in one table say
32
+ # which was saved first. A later version dated earlier was usually dated
33
+ # by PaperTrail at an `updated_at` the application set itself, and the
34
+ # history then reads it before the change it followed: an update dated
35
+ # before the record's create reads as the record deleted and created
36
+ # again. A time can also be right and the id wrong, as for versions
37
+ # imported from elsewhere, so this warns rather than refuses.
38
+ # : (Array[untyped]) -> DiagnosticIssue?
39
+ def inverted: (Array[untyped]) -> DiagnosticIssue?
40
+
41
+ # : (untyped, untyped) -> String
42
+ def inverted_message: (untyped, untyped) -> String
43
+
28
44
  # Loaded history orders versions that share a timestamp by id, but PT-AT
29
45
  # places association changes by timestamp alone, so a path it reads loses
30
46
  # any change between such a pair. Unlike an unorderable sequence this is
@@ -18,6 +18,9 @@ module PaperTrailDiff
18
18
  # : (untyped) -> untyped
19
19
  def self.separate_part: (untyped) -> untyped
20
20
 
21
+ # : (untyped) -> bool
22
+ def self.separate?: (untyped) -> bool
23
+
21
24
  # PT-AT's version association rows joined to the versions they were saved
22
25
  # with. Its `belongs_to :version` names PaperTrail's default class whatever
23
26
  # table a model's versions are in, so the join names the table instead.
@@ -9,33 +9,33 @@ module PaperTrailDiff
9
9
  SUPPORTED_ASSOCIATION_MACROS: untyped
10
10
 
11
11
  # Compares net state between explicit PaperTrail-version or current-record endpoints.
12
- # : (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
13
- def self.compare: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
12
+ # : (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> Diff
13
+ def self.compare: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> Diff
14
14
 
15
15
  # Compares many independent endpoint pairs while batching current-record loading.
16
- # : (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
17
- def self.compare_many: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
16
+ # : (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> comparison_results
17
+ def self.compare_many: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?allow_approximate: bool) -> comparison_results
18
18
 
19
19
  # Compares every adjacent reconstructed state in an inclusive version range,
20
20
  # by default the record's whole history through its current state.
21
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
22
- def self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
21
+ # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?allow_approximate: bool) -> Array[Step]
22
+ def self.timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?allow_approximate: bool) -> Array[Step]
23
23
 
24
24
  # Compares adjacent root and selected-descendant activity boundaries.
25
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
26
- def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
25
+ # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
26
+ def self.activity_timeline: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
27
27
 
28
28
  # Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
29
- # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
30
- def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
29
+ # : (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
30
+ def self.analyze: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
31
31
 
32
32
  # Analyzes an array of records over one shared range, preparing their
33
33
  # selected history once for the batch instead of once per record, and
34
34
  # returns a frozen Hash keyed by identity. Roots with nothing to report in
35
35
  # the window return an empty `Analysis`. To let a relation choose the
36
36
  # records, use `analyze_scope`.
37
- # : (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
38
- def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
37
+ # : (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
38
+ def self.analyze_many: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
39
39
 
40
40
  # Analyzes every root the relation reaches whose history moved inside the
41
41
  # window. With `activity: true`, a change to a record on one of the
@@ -63,15 +63,15 @@ module PaperTrailDiff
63
63
  # Note also that a relation selects on current state, not on state during
64
64
  # the window: `where(status: 'published')` means published *now*, which is a
65
65
  # different set from what was published while the window was open.
66
- # : (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
67
- def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
66
+ # : (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
67
+ def self.analyze_scope: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
68
68
 
69
69
  # Recent root and selected-child activity through the current saved state,
70
70
  # for every root that changed or whose requested associations did.
71
71
  # Historical windows remain explicit on analyze_scope; this entry point is
72
72
  # deliberately named for a report through now rather than an as-of query.
73
- # : (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
74
- def self.report: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
73
+ # : (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
74
+ def self.report: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
75
75
 
76
76
  # Warns about deprecated options; see Deprecation.
77
77
  # : () -> untyped
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: paper_trail_diff
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.15.0
4
+ version: 0.17.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Alex Williams
@@ -50,7 +50,7 @@ dependencies:
50
50
  - !ruby/object:Gem::Version
51
51
  version: '18'
52
52
  description: |
53
- paper_trail_diff compares reified PaperTrail histories and returns structured
53
+ paper_trail_diff compares records across their PaperTrail history and returns structured
54
54
  attribute and explicitly selected association changes.
55
55
  email:
56
56
  - alex.williams.dev@gmail.com
@@ -84,6 +84,7 @@ files:
84
84
  - lib/paper_trail_diff/activity_relationship.rb
85
85
  - lib/paper_trail_diff/activity_root_snapshot_refresher.rb
86
86
  - lib/paper_trail_diff/activity_root_steps.rb
87
+ - lib/paper_trail_diff/activity_scope_filter.rb
87
88
  - lib/paper_trail_diff/activity_snapshot_delta.rb
88
89
  - lib/paper_trail_diff/activity_snapshot_sequence.rb
89
90
  - lib/paper_trail_diff/activity_target_candidate_loader.rb
@@ -103,9 +104,11 @@ files:
103
104
  - lib/paper_trail_diff/association_traversal.rb
104
105
  - lib/paper_trail_diff/batch_boundary_resolver.rb
105
106
  - lib/paper_trail_diff/batch_preload.rb
107
+ - lib/paper_trail_diff/batched_root_analyses.rb
106
108
  - lib/paper_trail_diff/batched_root_analyzer.rb
107
109
  - lib/paper_trail_diff/batched_root_versions.rb
108
110
  - lib/paper_trail_diff/branch_snapshot_refresher.rb
111
+ - lib/paper_trail_diff/change_attribution.rb
109
112
  - lib/paper_trail_diff/change_row.rb
110
113
  - lib/paper_trail_diff/collection_comparator.rb
111
114
  - lib/paper_trail_diff/collection_identity_index.rb
@@ -131,18 +134,23 @@ files:
131
134
  - lib/paper_trail_diff/live_endpoint_provider.rb
132
135
  - lib/paper_trail_diff/live_graph_collector.rb
133
136
  - lib/paper_trail_diff/nested_comparator.rb
137
+ - lib/paper_trail_diff/net_change.rb
138
+ - lib/paper_trail_diff/own_window.rb
134
139
  - lib/paper_trail_diff/paper_trail_adapter.rb
135
- - lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb
136
140
  - lib/paper_trail_diff/prepared_activity_index.rb
137
141
  - lib/paper_trail_diff/prepared_association_reifier.rb
142
+ - lib/paper_trail_diff/prepared_child_candidates.rb
138
143
  - lib/paper_trail_diff/prepared_edge_loader.rb
139
144
  - lib/paper_trail_diff/prepared_history.rb
140
145
  - lib/paper_trail_diff/prepared_history_loader.rb
141
146
  - lib/paper_trail_diff/prepared_record_index.rb
142
147
  - lib/paper_trail_diff/prepared_snapshot_builder.rb
143
148
  - lib/paper_trail_diff/prepared_state_association_reader.rb
149
+ - lib/paper_trail_diff/read_snapshot.rb
144
150
  - lib/paper_trail_diff/recorded_changes.rb
151
+ - lib/paper_trail_diff/recorded_changes_reader.rb
145
152
  - lib/paper_trail_diff/recorded_class.rb
153
+ - lib/paper_trail_diff/recorded_columns.rb
146
154
  - lib/paper_trail_diff/root_version_plan.rb
147
155
  - lib/paper_trail_diff/root_version_selection.rb
148
156
  - lib/paper_trail_diff/scope_condition.rb
@@ -154,13 +162,17 @@ files:
154
162
  - lib/paper_trail_diff/snapshot_normalizer.rb
155
163
  - lib/paper_trail_diff/snapshot_traversal.rb
156
164
  - lib/paper_trail_diff/step.rb
165
+ - lib/paper_trail_diff/stored_json_values.rb
157
166
  - lib/paper_trail_diff/stored_time_precision.rb
167
+ - lib/paper_trail_diff/stored_values.rb
158
168
  - lib/paper_trail_diff/support.rb
169
+ - lib/paper_trail_diff/time_of_day.rb
159
170
  - lib/paper_trail_diff/time_range.rb
160
171
  - lib/paper_trail_diff/time_version_range.rb
161
172
  - lib/paper_trail_diff/timeline_builder.rb
162
173
  - lib/paper_trail_diff/timeline_range.rb
163
174
  - lib/paper_trail_diff/timeline_snapshot_provider.rb
175
+ - lib/paper_trail_diff/total_order.rb
164
176
  - lib/paper_trail_diff/transaction_cut.rb
165
177
  - lib/paper_trail_diff/traversal.rb
166
178
  - lib/paper_trail_diff/traversal_emitter.rb
@@ -193,6 +205,7 @@ files:
193
205
  - sig/generated/paper_trail_diff/activity_relationship.rbs
194
206
  - sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs
195
207
  - sig/generated/paper_trail_diff/activity_root_steps.rbs
208
+ - sig/generated/paper_trail_diff/activity_scope_filter.rbs
196
209
  - sig/generated/paper_trail_diff/activity_snapshot_delta.rbs
197
210
  - sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs
198
211
  - sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs
@@ -212,9 +225,11 @@ files:
212
225
  - sig/generated/paper_trail_diff/association_traversal.rbs
213
226
  - sig/generated/paper_trail_diff/batch_boundary_resolver.rbs
214
227
  - sig/generated/paper_trail_diff/batch_preload.rbs
228
+ - sig/generated/paper_trail_diff/batched_root_analyses.rbs
215
229
  - sig/generated/paper_trail_diff/batched_root_analyzer.rbs
216
230
  - sig/generated/paper_trail_diff/batched_root_versions.rbs
217
231
  - sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs
232
+ - sig/generated/paper_trail_diff/change_attribution.rbs
218
233
  - sig/generated/paper_trail_diff/change_row.rbs
219
234
  - sig/generated/paper_trail_diff/collection_comparator.rbs
220
235
  - sig/generated/paper_trail_diff/collection_identity_index.rbs
@@ -240,18 +255,23 @@ files:
240
255
  - sig/generated/paper_trail_diff/live_endpoint_provider.rbs
241
256
  - sig/generated/paper_trail_diff/live_graph_collector.rbs
242
257
  - sig/generated/paper_trail_diff/nested_comparator.rbs
258
+ - sig/generated/paper_trail_diff/net_change.rbs
259
+ - sig/generated/paper_trail_diff/own_window.rbs
243
260
  - sig/generated/paper_trail_diff/paper_trail_adapter.rbs
244
- - sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs
245
261
  - sig/generated/paper_trail_diff/prepared_activity_index.rbs
246
262
  - sig/generated/paper_trail_diff/prepared_association_reifier.rbs
263
+ - sig/generated/paper_trail_diff/prepared_child_candidates.rbs
247
264
  - sig/generated/paper_trail_diff/prepared_edge_loader.rbs
248
265
  - sig/generated/paper_trail_diff/prepared_history.rbs
249
266
  - sig/generated/paper_trail_diff/prepared_history_loader.rbs
250
267
  - sig/generated/paper_trail_diff/prepared_record_index.rbs
251
268
  - sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs
252
269
  - sig/generated/paper_trail_diff/prepared_state_association_reader.rbs
270
+ - sig/generated/paper_trail_diff/read_snapshot.rbs
253
271
  - sig/generated/paper_trail_diff/recorded_changes.rbs
272
+ - sig/generated/paper_trail_diff/recorded_changes_reader.rbs
254
273
  - sig/generated/paper_trail_diff/recorded_class.rbs
274
+ - sig/generated/paper_trail_diff/recorded_columns.rbs
255
275
  - sig/generated/paper_trail_diff/root_version_plan.rbs
256
276
  - sig/generated/paper_trail_diff/root_version_selection.rbs
257
277
  - sig/generated/paper_trail_diff/scope_condition.rbs
@@ -263,13 +283,17 @@ files:
263
283
  - sig/generated/paper_trail_diff/snapshot_normalizer.rbs
264
284
  - sig/generated/paper_trail_diff/snapshot_traversal.rbs
265
285
  - sig/generated/paper_trail_diff/step.rbs
286
+ - sig/generated/paper_trail_diff/stored_json_values.rbs
266
287
  - sig/generated/paper_trail_diff/stored_time_precision.rbs
288
+ - sig/generated/paper_trail_diff/stored_values.rbs
267
289
  - sig/generated/paper_trail_diff/support.rbs
290
+ - sig/generated/paper_trail_diff/time_of_day.rbs
268
291
  - sig/generated/paper_trail_diff/time_range.rbs
269
292
  - sig/generated/paper_trail_diff/time_version_range.rbs
270
293
  - sig/generated/paper_trail_diff/timeline_builder.rbs
271
294
  - sig/generated/paper_trail_diff/timeline_range.rbs
272
295
  - sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs
296
+ - sig/generated/paper_trail_diff/total_order.rbs
273
297
  - sig/generated/paper_trail_diff/transaction_cut.rbs
274
298
  - sig/generated/paper_trail_diff/traversal.rbs
275
299
  - sig/generated/paper_trail_diff/traversal_emitter.rbs
@@ -290,11 +314,11 @@ licenses:
290
314
  metadata:
291
315
  allowed_push_host: https://rubygems.org
292
316
  bug_tracker_uri: https://github.com/aheathwilliams/paper_trail_diff/issues
293
- changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.15.0/CHANGELOG.md
294
- documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.15.0/README.md
317
+ changelog_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.17.0/CHANGELOG.md
318
+ documentation_uri: https://github.com/aheathwilliams/paper_trail_diff/blob/v0.17.0/README.md
295
319
  homepage_uri: https://github.com/aheathwilliams/paper_trail_diff
296
320
  rubygems_mfa_required: 'true'
297
- source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.15.0
321
+ source_code_uri: https://github.com/aheathwilliams/paper_trail_diff/tree/v0.17.0
298
322
  rdoc_options: []
299
323
  require_paths:
300
324
  - lib
@@ -1,60 +0,0 @@
1
- # frozen_string_literal: true
2
- # rbs_inline: enabled
3
-
4
- module PaperTrailDiff
5
- # Validates and reuses caller-owned live records, reading again only the
6
- # associations a preload of many records cannot have loaded correctly.
7
- class PreloadedEndpointBatchLoader
8
- #: (tree: AssociationTree, traversal: AssociationTraversal) -> void
9
- def initialize(tree:, traversal:)
10
- @tree = tree
11
- @traversal = traversal
12
- end
13
-
14
- #: (Array[untyped]) -> Hash[identity, untyped]
15
- def call(records)
16
- records.each { |record| validate_record(record, @tree, path: '') }
17
- records.to_h { |record| [Endpoint.identity(record), record] }
18
- end
19
-
20
- private
21
-
22
- # @rbs @tree: AssociationTree
23
- # @rbs @traversal: AssociationTraversal
24
-
25
- #: (untyped, AssociationTree, path: String) -> void
26
- def validate_record(record, tree, path:)
27
- @traversal.reflections_for(record.class, tree, path: path).each do |reflection|
28
- validate_association(record, tree, path, reflection)
29
- end
30
- end
31
-
32
- #: (untyped, AssociationTree, String, untyped) -> void
33
- def validate_association(record, tree, path, reflection)
34
- association_path = Support.association_path(path, reflection.name)
35
- association = record.association(reflection.name)
36
- unless association.loaded?
37
- message = "current endpoint association is not preloaded: #{association_path}"
38
- raise UnloadedAssociationError, message
39
- end
40
- read_alone(association) unless BatchPreload.safe?(reflection)
41
-
42
- subtree = tree.child(reflection.name)
43
- return unless subtree
44
-
45
- Array(association.target).compact.each do |child|
46
- validate_record(child, subtree, path: association_path)
47
- end
48
- end
49
-
50
- # Preloading many records applies a limit or offset to all of them
51
- # together, so what a caller preloaded cannot be trusted: one record keeps
52
- # another's share, or none. Such an association is read again for each
53
- # record, as reloading reads it.
54
- #: (untyped) -> void
55
- def read_alone(association)
56
- association.reset
57
- association.load_target
58
- end
59
- end
60
- end
@@ -1,32 +0,0 @@
1
- # Generated from lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb with RBS::Inline
2
-
3
- module PaperTrailDiff
4
- # Validates and reuses caller-owned live records, reading again only the
5
- # associations a preload of many records cannot have loaded correctly.
6
- class PreloadedEndpointBatchLoader
7
- # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
8
- def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
9
-
10
- # : (Array[untyped]) -> Hash[identity, untyped]
11
- def call: (Array[untyped]) -> Hash[identity, untyped]
12
-
13
- private
14
-
15
- @traversal: AssociationTraversal
16
-
17
- @tree: AssociationTree
18
-
19
- # : (untyped, AssociationTree, path: String) -> void
20
- def validate_record: (untyped, AssociationTree, path: String) -> void
21
-
22
- # : (untyped, AssociationTree, String, untyped) -> void
23
- def validate_association: (untyped, AssociationTree, String, untyped) -> void
24
-
25
- # Preloading many records applies a limit or offset to all of them
26
- # together, so what a caller preloaded cannot be trusted: one record keeps
27
- # another's share, or none. Such an association is read again for each
28
- # record, as reloading reads it.
29
- # : (untyped) -> void
30
- def read_alone: (untyped) -> void
31
- end
32
- end