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
@@ -2,16 +2,20 @@
2
2
 
3
3
  module PaperTrailDiff
4
4
  # Reconstructs and caches immutable historical snapshots for one adapter
5
- # configuration. It keeps the histories batches prepare, by root version;
6
- # one prepared for a single root goes back to the caller, who passes it to
7
- # every read for that root.
5
+ # configuration. It keeps the histories batches prepare, by root and by root
6
+ # version; one prepared for a single root goes back to the caller, who
7
+ # passes it to every read for that root.
8
8
  class HistoricalSnapshotStore
9
- # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
10
- def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
9
+ # : (traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
10
+ def initialize: (traversal: AssociationTraversal, normalizer: SnapshotNormalizer, preparer: untyped) -> void
11
11
 
12
+ # A `start_at` is a window's (see PreparedHistoryLoader); a range of
13
+ # versions starts at its first.
12
14
  # : (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
13
15
  def prepare: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
14
16
 
17
+ # A `start_at` is a window's, as for `prepare`. A window's roots may have
18
+ # no version in it, when only their descendants changed there.
15
19
  # : (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
16
20
  def prepare_batch: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
17
21
 
@@ -31,15 +35,25 @@ module PaperTrailDiff
31
35
  # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
32
36
  def custom: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
33
37
 
38
+ # The state a snapshot of the root at this endpoint starts from when built
39
+ # from prepared history: the one a version stored, or the live row's.
40
+ # Nil where a version's is read another way.
41
+ # : (untyped) -> PreparedRecordState?
42
+ def root_state: (untyped) -> PreparedRecordState?
43
+
34
44
  # : (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
35
45
  def association_reader: (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
36
46
 
37
47
  private
38
48
 
49
+ @batched_roots: Hash[identity, PreparedHistory]
50
+
39
51
  @live_graph_collector: LiveGraphCollector
40
52
 
41
53
  @live_roots: Hash[identity, untyped]
42
54
 
55
+ @live_states: Hash[identity, PreparedRecordState]
56
+
43
57
  @normalizer: SnapshotNormalizer
44
58
 
45
59
  @prepared_histories: Hash[Array[untyped], PreparedHistory]
@@ -58,27 +72,43 @@ module PaperTrailDiff
58
72
  # : (untyped, PreparedHistory?) -> PreparedHistory?
59
73
  def history_for: (untyped, PreparedHistory?) -> PreparedHistory?
60
74
 
61
- # : (untyped) -> Array[untyped]
62
- def context_key: (untyped) -> Array[untyped]
63
-
64
75
  # : (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
65
76
  def batch_payload: (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
66
77
 
67
78
  # : (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
68
79
  def register_batch: (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
69
80
 
81
+ # Snapshot reads find the history by root version, and `prepare` by root.
82
+ # : (PreparedHistory, Array[untyped], Array[untyped]) -> void
83
+ def register: (PreparedHistory, Array[untyped], Array[untyped]) -> void
84
+
70
85
  # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
71
86
  def snapshot_from_version: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
72
87
 
88
+ # Read from prepared history where it can be, as a version is, without
89
+ # instantiating the root's members. Only the fallback, which writes the
90
+ # members it rebuilds onto the root, needs a record of its own.
73
91
  # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
74
92
  def snapshot_from_live_root: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
75
93
 
94
+ # The state of the root's row, read once for the call: every snapshot
95
+ # that starts from the row starts from the same state. Reading it writes
96
+ # nothing to the row, so it is read from the loaded record itself, whose
97
+ # columns the current snapshot reads too.
98
+ # : (untyped) -> PreparedRecordState
99
+ def live_state: (untyped) -> PreparedRecordState
100
+
76
101
  # Rebuilding a version's associations writes them onto the record, so each
77
- # snapshot gets its own copy of a batch's loaded row, built from the row's
78
- # stored values without a query.
102
+ # snapshot that does gets its own copy of the root's row, built from the
103
+ # row's stored values without a query.
79
104
  # : (untyped) -> untyped
80
105
  def live_root: (untyped) -> untyped
81
106
 
107
+ # A batch loaded the row already; otherwise it is read once, so every
108
+ # snapshot of the call starts from the same row.
109
+ # : (untyped, identity) -> untyped
110
+ def loaded_root: (untyped, identity) -> untyped
111
+
82
112
  # : (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
83
113
  def normalize: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
84
114
 
@@ -10,8 +10,5 @@ module PaperTrailDiff
10
10
  # result may be incomplete and only the application can judge that.
11
11
  # : (String | Symbol, Hash[Symbol, untyped]) -> void
12
12
  def self?.notify: (String | Symbol, Hash[Symbol, untyped]) -> void
13
-
14
- # : (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
15
- def self?.comparison_payload: (association_paths: Array[String], reload_live_endpoints: bool) -> Hash[Symbol, untyped]
16
13
  end
17
14
  end
@@ -13,9 +13,12 @@ module PaperTrailDiff
13
13
 
14
14
  @tree: AssociationTree
15
15
 
16
+ # Each statement reads 500 records.
16
17
  # : (untyped, Array[untyped]) -> Array[untyped]
17
18
  def load_group: (untyped, Array[untyped]) -> Array[untyped]
18
19
 
20
+ # Active Record preloads an association of all the records it is given in
21
+ # one statement, so they are given 500 at a time.
19
22
  # : (Array[untyped], AssociationTree) -> void
20
23
  def preload_tree: (Array[untyped], AssociationTree) -> void
21
24
 
@@ -1,14 +1,11 @@
1
1
  # Generated from lib/paper_trail_diff/live_endpoint_provider.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Selects safe reload or validated caller-owned loading for current endpoints.
4
+ # Reloads the current records a call compares with, with their requested
5
+ # associations, once per call.
5
6
  class LiveEndpointProvider
6
- attr_reader reload: bool
7
-
8
- attr_reader comparison_payload: Hash[Symbol, untyped]
9
-
10
- # : (tree: AssociationTree, traversal: AssociationTraversal, reload: bool) -> void
11
- def initialize: (tree: AssociationTree, traversal: AssociationTraversal, reload: bool) -> void
7
+ # : (tree: AssociationTree) -> void
8
+ def initialize: (tree: AssociationTree) -> void
12
9
 
13
10
  # Loads each endpoint at most once for the life of this provider, which is
14
11
  # one public call. A batch that resolves every root up front and then asks
@@ -21,7 +18,7 @@ module PaperTrailDiff
21
18
 
22
19
  @loaded: Hash[identity, untyped]
23
20
 
24
- @loader: untyped
21
+ @loader: LiveEndpointBatchLoader
25
22
 
26
23
  # : (Array[untyped]) -> Hash[identity, untyped]
27
24
  def known: (Array[untyped]) -> Hash[identity, untyped]
@@ -3,8 +3,8 @@
3
3
  module PaperTrailDiff
4
4
  # Flattens an already-preloaded, explicitly bounded live association graph.
5
5
  class LiveGraphCollector
6
- # : (tree: AssociationTree, traversal: AssociationTraversal) -> void
7
- def initialize: (tree: AssociationTree, traversal: AssociationTraversal) -> void
6
+ # : (AssociationTraversal) -> void
7
+ def initialize: (AssociationTraversal) -> void
8
8
 
9
9
  # : (Array[untyped]) -> Array[untyped]
10
10
  def call: (Array[untyped]) -> Array[untyped]
@@ -22,6 +22,10 @@ module PaperTrailDiff
22
22
  # An absent key is not a null one. `{"a": null}` and `{}` mean different
23
23
  # things in JSON and an audit trail that conflated them would be lying about
24
24
  # one of them, so absence is its own value rather than nil.
25
+ #
26
+ # A key is its name: `:a` and `"a"` are one key at any depth, inside arrays
27
+ # too, because a hash built in Ruby and one read back from JSON key the same
28
+ # field differently. Values are reported as they were given.
25
29
  class NestedComparator
26
30
  # Stands in for a key that was not there at all.
27
31
  class Absent
@@ -37,6 +41,16 @@ module PaperTrailDiff
37
41
  # : (untyped, untyped) -> nested_changes
38
42
  def self.call: (untyped, untyped) -> nested_changes
39
43
 
44
+ # The value as it is compared: every Hash key read as a string, at any
45
+ # depth and inside arrays, and everything else as it is.
46
+ # : (untyped) -> untyped
47
+ def self.comparable: (untyped) -> untyped
48
+
49
+ # The hash keyed by name, each value as the block returns it. Two keys
50
+ # with one name, such as `:a` and `"a"`, cannot both be kept.
51
+ # : (Hash[untyped, untyped]) { (untyped) -> untyped } -> Hash[String, untyped]
52
+ def self.string_keyed: (Hash[untyped, untyped]) { (untyped) -> untyped } -> Hash[String, untyped]
53
+
40
54
  # : (untyped, untyped) -> void
41
55
  def initialize: (untyped, untyped) -> void
42
56
 
@@ -70,10 +84,12 @@ module PaperTrailDiff
70
84
  # : (Hash[untyped, untyped]) -> Hash[String, untyped]
71
85
  def normalize_keys: (Hash[untyped, untyped]) -> Hash[String, untyped]
72
86
 
73
- # Two arrays are a membership change; anything else is a change to the
74
- # value as a whole, including an array facing something that is not one.
75
- # : (untyped, untyped) -> nested_change
76
- def change_for: (untyped, untyped) -> nested_change
87
+ # Two arrays are a membership change, or none when they hold the same
88
+ # elements in the same order once keys are read as strings; anything else
89
+ # is a change to the value as a whole, including an array facing something
90
+ # that is not one.
91
+ # : (untyped, untyped) -> nested_change?
92
+ def change_for: (untyped, untyped) -> nested_change?
77
93
 
78
94
  # Sorted so a report reads the same twice. Both hashes are already keyed by
79
95
  # strings, because a hash loaded from JSON and one built in Ruby can key the
@@ -0,0 +1,168 @@
1
+ # Generated from lib/paper_trail_diff/net_change.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # One record's net change over the change rows a caller kept: its state
5
+ # before them, and that state with only the kept changes made. Built by
6
+ # Analysis#net_changes (see NetChanges).
7
+ class NetChange
8
+ attr_reader association_path: Array[String]
9
+
10
+ attr_reader association_kind: Symbol?
11
+
12
+ # The record, or nil for the root itself, as on a change row.
13
+ attr_reader record: RecordReference?
14
+
15
+ # The record's fields when the step holding its first kept change began,
16
+ # or nil where it was not there. The records it holds are left out: each
17
+ # has an entry of its own.
18
+ attr_reader before: RecordSnapshot?
19
+
20
+ # `before` with only the kept changes made, or nil where they removed the
21
+ # record.
22
+ attr_reader after: RecordSnapshot?
23
+
24
+ # `before` compared with `after`: the fields that differ, or the record's
25
+ # appearance or removal.
26
+ attr_reader diff: Diff
27
+
28
+ # The events that made the kept changes, in order, each once.
29
+ attr_reader sources: Array[ActivityBoundary]
30
+
31
+ # : (association_path: Array[String], association_kind: Symbol?, record: RecordReference?, before: RecordSnapshot?, after: RecordSnapshot?, sources: Array[ActivityBoundary]) -> void
32
+ def initialize: (association_path: Array[String], association_kind: Symbol?, record: RecordReference?, before: RecordSnapshot?, after: RecordSnapshot?, sources: Array[ActivityBoundary]) -> void
33
+
34
+ # : () -> bool
35
+ def root?: () -> bool
36
+
37
+ # Whether the record was not there before its first kept change.
38
+ # : () -> bool
39
+ def added?: () -> bool
40
+
41
+ # Whether the kept changes left the record gone.
42
+ # : () -> bool
43
+ def removed?: () -> bool
44
+
45
+ # : () -> Hash[Symbol, untyped]
46
+ def to_h: () -> Hash[Symbol, untyped]
47
+ end
48
+
49
+ # Folds an activity timeline's change rows into one NetChange for each
50
+ # record a kept row is about, known by its association path and identity as
51
+ # the row names it.
52
+ #
53
+ # A record's `before` is its state in the snapshot that the step of its
54
+ # first kept row starts from. Each kept row then makes its change in time
55
+ # order: a field takes the row's new value, and a row about the whole record
56
+ # moves it in or out as the step's closing snapshot has it. A record that
57
+ # appears takes that snapshot's fields, so a field no kept row sets keeps
58
+ # the value it has there; the kept rows of its fields then replace any value
59
+ # a dropped row left.
60
+ class NetChanges
61
+ # What one record's kept rows have made of it so far.
62
+ class RecordFold
63
+ # The rows that set a field; a removed record's rows leave them be.
64
+ SETTING: untyped
65
+
66
+ # : (ChangeRow, RecordSnapshot?) -> void
67
+ def initialize: (ChangeRow, RecordSnapshot?) -> void
68
+
69
+ # Makes one step's kept rows of the record. The block finds the record
70
+ # in the step's closing snapshot, which only a row about the whole
71
+ # record needs.
72
+ # : (Array[ChangeRow]) { () -> RecordSnapshot? } -> void
73
+ def apply: (Array[ChangeRow]) { () -> RecordSnapshot? } -> void
74
+
75
+ # : () -> NetChange
76
+ def net_change: () -> NetChange
77
+
78
+ private
79
+
80
+ @before: RecordSnapshot?
81
+
82
+ @present: bool
83
+
84
+ @read: RecordSnapshot?
85
+
86
+ @row: ChangeRow
87
+
88
+ @sources: Array[ActivityBoundary]
89
+
90
+ @values: Hash[String, untyped]
91
+
92
+ # A record that appears, or moves between the records holding it, takes
93
+ # its fields from where it ends up, which an added row's step holds.
94
+ # : (Array[ChangeRow], RecordSnapshot?) -> void
95
+ def move: (Array[ChangeRow], RecordSnapshot?) -> void
96
+
97
+ # A record is there only once its own state was read, before its first
98
+ # kept row or where it appeared.
99
+ # : () -> RecordSnapshot?
100
+ def after: () -> RecordSnapshot?
101
+ end
102
+
103
+ # `keep` picks the rows to make; without it, every row is made.
104
+ # : (Array[ActivityStep], (^(ChangeRow) -> boolish)?) -> Array[NetChange]
105
+ def self.call: (Array[ActivityStep], (^(ChangeRow) -> boolish)?) -> Array[NetChange]
106
+
107
+ # : (Array[ActivityStep], (^(ChangeRow) -> boolish)?) -> void
108
+ def initialize: (Array[ActivityStep], (^(ChangeRow) -> boolish)?) -> void
109
+
110
+ # : () -> Array[NetChange]
111
+ def call: () -> Array[NetChange]
112
+
113
+ private
114
+
115
+ @folds: Hash[Array[untyped], RecordFold]
116
+
117
+ @holders: Hash[[ RecordSnapshot, Array[String] ], Array[RecordSnapshot]]
118
+
119
+ @keep: (^(ChangeRow) -> boolish)?
120
+
121
+ @opening_root: RecordSnapshot?
122
+
123
+ @steps: Array[ActivityStep]
124
+
125
+ # A step with a change has a state on at least one side, which it keeps
126
+ # only when asked to.
127
+ # : () -> void
128
+ def check_snapshots!: () -> void
129
+
130
+ # : (ActivityStep) -> Array[ChangeRow]
131
+ def kept: (ActivityStep) -> Array[ChangeRow]
132
+
133
+ # : (ChangeRow) -> Array[untyped]
134
+ def key: (ChangeRow) -> Array[untyped]
135
+
136
+ # : (Array[untyped], ActivityStep, Array[ChangeRow]) -> void
137
+ def fold: (Array[untyped], ActivityStep, Array[ChangeRow]) -> void
138
+
139
+ # The root comes first whenever anything is listed, so a report has its
140
+ # fields when only the records it holds changed; then each record in the
141
+ # order of its first kept change. A record the kept changes left as it
142
+ # was is left out.
143
+ # : () -> Array[NetChange]
144
+ def listed: () -> Array[NetChange]
145
+
146
+ # The root, without a kept change of its own, as the first kept change
147
+ # found it.
148
+ # : () -> NetChange
149
+ def unchanged_root: () -> NetChange
150
+
151
+ # The record a row is about in one of its step's snapshots, under any of
152
+ # the records along its path; nil where it is not there.
153
+ # : (RecordSnapshot?, ChangeRow) -> RecordSnapshot?
154
+ def locate: (RecordSnapshot?, ChangeRow) -> RecordSnapshot?
155
+
156
+ # The records reached through `parents` from the root, read once for each
157
+ # snapshot.
158
+ # : (RecordSnapshot, Array[String]) -> Array[RecordSnapshot]
159
+ def holders: (RecordSnapshot, Array[String]) -> Array[RecordSnapshot]
160
+
161
+ # : (RecordSnapshot, Array[String]) -> Array[RecordSnapshot]
162
+ def reach: (RecordSnapshot, Array[String]) -> Array[RecordSnapshot]
163
+
164
+ # The record's own fields, without the records it holds.
165
+ # : (RecordSnapshot?) -> RecordSnapshot?
166
+ def flat: (RecordSnapshot?) -> RecordSnapshot?
167
+ end
168
+ end
@@ -0,0 +1,22 @@
1
+ # Generated from lib/paper_trail_diff/own_window.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Splits the versions read for a batch by each root's own window. A
5
+ # transaction that crosses an edge moves a root's window to start or end
6
+ # earlier (see TransactionCut), never later, so the versions read from the
7
+ # earliest start to the shared end hold each root's own, and the first left
8
+ # past an end that moved.
9
+ module OwnWindow
10
+ # From the earliest start to the shared end.
11
+ # : (TimeRange, Array[TimeRange]) -> TimeRange
12
+ def self.widest: (TimeRange, Array[TimeRange]) -> TimeRange
13
+
14
+ # The versions inside `window`, and the first of the rest past its end.
15
+ # They are read in no order, so the first is found by time and id.
16
+ # : (TimeRange, Array[untyped]) -> [Array[untyped], untyped]
17
+ def self.split: (TimeRange, Array[untyped]) -> [ Array[untyped], untyped ]
18
+
19
+ # : (Array[untyped], Time?) -> untyped
20
+ def self.first_past: (Array[untyped], Time?) -> untyped
21
+ end
22
+ end
@@ -8,8 +8,8 @@ module PaperTrailDiff
8
8
  class PaperTrailAdapter
9
9
  # `recorded_changes:` reads what each activity boundary's version recorded.
10
10
  # `allow_approximate:` accepts association paths read with PT-AT.
11
- # : (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
12
- def initialize: (associations: association_option, ignore: ignore_option, ?reload_live_endpoints: bool, ?recorded_changes: bool, ?allow_approximate: bool) -> void
11
+ # : (associations: association_option, ignore: ignore_option, ?recorded_changes: bool, ?allow_approximate: bool) -> void
12
+ def initialize: (associations: association_option, ignore: ignore_option, ?recorded_changes: bool, ?allow_approximate: bool) -> void
13
13
 
14
14
  # : (untyped, untyped) -> Diff
15
15
  def compare: (untyped, untyped) -> Diff
@@ -40,12 +40,18 @@ module PaperTrailDiff
40
40
 
41
41
  private
42
42
 
43
- # : (bool, bool, Symbol?) -> ActivityView
44
- def activity_view: (bool, bool, Symbol?) -> ActivityView
43
+ # : (bool, bool, Symbol?, untyped) -> ActivityView
44
+ def activity_view: (bool, bool, Symbol?, untyped) -> ActivityView
45
45
 
46
46
  # : (untyped) -> Hash[Symbol, untyped]
47
47
  def model_payload: (untyped) -> Hash[Symbol, untyped]
48
48
 
49
+ # : (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
50
+ def analyze_record: (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
51
+
52
+ # : (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> TimelineBuilder
53
+ def timeline_builder: (untyped, from: untyped, to: untyped, within: untyped, version_scope: untyped, live_endpoint: untyped) -> TimelineBuilder
54
+
49
55
  # : (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
50
56
  def analyze_batch: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
51
57
 
@@ -54,6 +60,10 @@ module PaperTrailDiff
54
60
  # : (untyped) -> void
55
61
  def check_scope: (untyped) -> void
56
62
 
63
+ # The endpoints of the hash comparisons. Anything else is left for the batch to refuse.
64
+ # : (untyped) -> Array[untyped]
65
+ def comparison_endpoints: (untyped) -> Array[untyped]
66
+
57
67
  # : (Array[comparison_input], preparer: untyped) -> ComparisonBatch
58
68
  def comparison_batch: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
59
69
 
@@ -64,6 +74,9 @@ module PaperTrailDiff
64
74
  # : (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
65
75
  def analyze_deleted: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
66
76
 
77
+ # : (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
78
+ def scoped_builder: (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
79
+
67
80
  @activity_snapshotter: ActivitySnapshotProvider
68
81
 
69
82
  @association_tree: AssociationTree
@@ -120,8 +133,8 @@ module PaperTrailDiff
120
133
  # : () -> void
121
134
  def build_snapshotters: () -> void
122
135
 
123
- # : (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
124
- def batched_root_analyzer: (bool, within: untyped, view: ActivityView) -> BatchedRootAnalyzer
136
+ # : (bool, view: ActivityView) -> BatchedRootAnalyzer
137
+ def batched_root_analyzer: (bool, view: ActivityView) -> BatchedRootAnalyzer
125
138
 
126
139
  # : () -> HistoricalSnapshotStore
127
140
  def build_historical_store: () -> HistoricalSnapshotStore
@@ -2,9 +2,20 @@
2
2
 
3
3
  module PaperTrailDiff
4
4
  # Shares association event discovery across every root in a prepared graph.
5
+ #
6
+ # The candidates are the records the prepared snapshots can hold: those
7
+ # recorded under an owner from the start onward, and those under it now. A
8
+ # key changed without a version is recorded only by the record's next
9
+ # version, or by the current row, either of which can come after the range,
10
+ # and the snapshots read it from there. ActivityTreeFilter leaves out the
11
+ # events of a candidate that was outside the tree throughout.
5
12
  class PreparedActivityIndex
6
- # : (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
7
- def initialize: (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
13
+ # The children the history's owners had, which its edge loader reads
14
+ # first for most of them.
15
+ attr_reader children: PreparedChildCandidates
16
+
17
+ # : (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
18
+ def initialize: (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
8
19
 
9
20
  # : (untyped, Array[untyped]) -> void
10
21
  def register: (untyped, Array[untyped]) -> void
@@ -22,18 +33,28 @@ module PaperTrailDiff
22
33
  # : (untyped, Array[untyped], ActivityRange) -> Array[untyped]
23
34
  def member_versions: (untyped, Array[untyped], ActivityRange) -> Array[untyped]
24
35
 
25
- # The versions of a through's join rows that are on its path. Under
26
- # `source_type:`, a row is on it only while its type column names that
27
- # class, so only the versions it had that type before or after count. A
28
- # version saved before the type column existed has no type to read.
29
- # : (Hash[Symbol, untyped], untyped) -> Array[untyped]
30
- def join_versions: (Hash[Symbol, untyped], untyped) -> Array[untyped]
31
-
36
+ # The versions of a through's join rows that are on its path (see
37
+ # ThroughPath). A row's versions in one transaction are judged together, by
38
+ # its states before the transaction and after it, as ActivityTreeFilter
39
+ # judges a record; a version saved outside a transaction is judged alone.
40
+ # A row created under another owner and moved here later, one that left,
41
+ # or one created and destroyed inside one transaction, saved versions that
42
+ # change nothing these `owners` show. As events they would open steps of
43
+ # their own, and inside a transaction, where a change surfaces one event
44
+ # late, take the credit for another record's change.
45
+ # : (Hash[Symbol, untyped], Hash[Symbol, untyped], untyped) -> Array[untyped]
46
+ def join_versions: (Hash[Symbol, untyped], Hash[Symbol, untyped], untyped) -> Array[untyped]
47
+
48
+ # Only the children the history loaded. Snapshots read children only under
49
+ # an owner the history prepared, and it loaded every child of those. An
50
+ # owner reached another way, such as a belongs_to target loaded for a
51
+ # different path, can have children the history never loaded, which no
52
+ # snapshot holds.
32
53
  # : (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
33
54
  def child_ids: (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
34
55
 
35
- # The `belongs_to` targets each owner pointed at in the range: at its start
36
- # and after each change inside it, plus the live row at a current end.
56
+ # The `belongs_to` targets each owner pointed at from the range's start
57
+ # onward, plus the live row and those its recorded states name.
37
58
  # : (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
38
59
  def target_rows: (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
39
60
 
@@ -47,20 +68,38 @@ module PaperTrailDiff
47
68
 
48
69
  private
49
70
 
50
- @children: Hash[untyped, untyped]
71
+ @conditions: ScopeCondition::Cache
51
72
 
52
73
  @nodes: Hash[String, Array[untyped]]
53
74
 
54
- @range: ActivityRange
55
-
56
75
  @records: PreparedRecordIndex
57
76
 
58
77
  @roots: Hash[Array[String], Array[untyped]]
59
78
 
60
79
  @rows: Hash[untyped, Hash[String, Array[untyped]]]
61
80
 
81
+ @start_at: untyped
82
+
62
83
  @targets: Hash[untyped, untyped]
63
84
 
85
+ # The versions one row saved in one transaction, or alone.
86
+ # : (untyped) -> Array[untyped]
87
+ def join_run: (untyped) -> Array[untyped]
88
+
89
+ # A run's versions are in the order they were saved, as the row's series
90
+ # holds them.
91
+ # : (untyped, Array[untyped], ThroughPath) -> bool
92
+ def on_path?: (untyped, Array[untyped], ThroughPath) -> bool
93
+
94
+ # The targets the owners' recorded states point at. PT-AT names a target
95
+ # only in the rows its owner's versions wrote, so a key changed without a
96
+ # version, such as one `has_paper_trail only:` leaves out, names its target
97
+ # only in the state the owner's next version recorded. Prepared history
98
+ # reads that state, so its snapshots show the target, and the target's
99
+ # versions are events too. A key of two columns is read per record instead.
100
+ # : (untyped, Array[untyped], untyped) -> Array[ActivityTargetCandidateLoader::Row]
101
+ def recorded_target_rows: (untyped, Array[untyped], untyped) -> Array[ActivityTargetCandidateLoader::Row]
102
+
64
103
  # : (untyped, Array[untyped]) -> bool
65
104
  def member_class?: (untyped, Array[untyped]) -> bool
66
105
 
@@ -70,9 +109,6 @@ module PaperTrailDiff
70
109
  # : (untyped) -> Array[untyped]
71
110
  def node_ids: (untyped) -> Array[untyped]
72
111
 
73
- # : (untyped, untyped) -> untyped
74
- def child_rows: (untyped, untyped) -> untyped
75
-
76
112
  # : (Hash[String, Array[ActivityTargetCandidateLoader::Row]], Array[untyped]) -> Array[ActivityTargetCandidateLoader::Row]
77
113
  def rows_for: (Hash[String, Array[ActivityTargetCandidateLoader::Row]], Array[untyped]) -> Array[ActivityTargetCandidateLoader::Row]
78
114
 
@@ -85,14 +121,74 @@ module PaperTrailDiff
85
121
  # Mirrors VersionAssociationCandidateScope's before-window rule. The loaded
86
122
  # series includes changes to other owners too, so an old membership cannot
87
123
  # survive a later pre-window reassignment just because that owner is absent.
124
+ # A range starting at a version starts before that version's transaction,
125
+ # as the scope's start does (see VersionBoundary.transaction_start), so a
126
+ # membership that ended earlier in that transaction still held there.
88
127
  # : (untyped, untyped, untyped, String?, ActivityRange) -> bool
89
128
  def eligible_version?: (untyped, untyped, untyped, String?, ActivityRange) -> bool
90
129
 
130
+ # Each statement reads the rows of 500 transactions.
91
131
  # : (untyped, untyped) -> Hash[String, Array[untyped]]
92
132
  def load_habtm_rows: (untyped, untyped) -> Hash[String, Array[untyped]]
93
133
 
94
134
  # A version without a transaction id names no rows, so it can stay in.
95
135
  # : (Array[untyped]) -> Array[untyped]
96
136
  def transaction_ids: (Array[untyped]) -> Array[untyped]
137
+
138
+ # Whether one state of a through's join row puts it on the through's path.
139
+ # The row must join one of the owners as the join association reads it: by
140
+ # its key, by the owner's type under `as:`, by its class when the
141
+ # association is to a subclass, and by the association's scope when the
142
+ # gem can read it, unranked, as a through reads its parts. A through that
143
+ # goes through a belongs_to, or through another through, is joined by the
144
+ # owner's key or by rows further down, which a row's own state cannot
145
+ # show. Under `source_type:`, the row's type column must name that class;
146
+ # a version saved before the column existed has no type to read.
147
+ class ThroughPath
148
+ # : (Hash[Symbol, untyped], untyped, ScopeCondition::Cache) -> void
149
+ def initialize: (Hash[Symbol, untyped], untyped, ScopeCondition::Cache) -> void
150
+
151
+ # Whether every state of a row is on the path, so that none need be read.
152
+ # : () -> bool
153
+ def open?: () -> bool
154
+
155
+ # : (Hash[untyped, untyped]) -> bool
156
+ def include?: (Hash[untyped, untyped]) -> bool
157
+
158
+ private
159
+
160
+ @conditions: ScopeCondition::Cache
161
+
162
+ @ids: Set[String]
163
+
164
+ @keyed: bool
165
+
166
+ @owner_types: Array[String]?
167
+
168
+ @reflection: untyped
169
+
170
+ @through: untyped
171
+
172
+ # : () -> bool
173
+ def keyed?: () -> bool
174
+
175
+ # : (Hash[untyped, untyped]) -> bool
176
+ def joined?: (Hash[untyped, untyped]) -> bool
177
+
178
+ # The names an `as:` row's type column may hold for an owner.
179
+ # : (untyped) -> Array[String]?
180
+ def owner_types: (untyped) -> Array[String]?
181
+
182
+ # : (Hash[untyped, untyped]) -> bool
183
+ def owner_type?: (Hash[untyped, untyped]) -> bool
184
+
185
+ # : (Hash[untyped, untyped]) -> bool
186
+ def in_scope?: (Hash[untyped, untyped]) -> bool
187
+
188
+ # As the through's snapshots read a join row (see
189
+ # PreparedStateAssociationReader#typed_join?).
190
+ # : (Hash[untyped, untyped]) -> bool
191
+ def typed?: (Hash[untyped, untyped]) -> bool
192
+ end
97
193
  end
98
194
  end