paper_trail_diff 0.16.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 +566 -1
  3. data/README.md +42 -7
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +86 -38
  6. data/docs/reference.md +309 -92
  7. data/docs/testing.md +240 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +3 -13
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +29 -29
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +2 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +74 -40
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +194 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +19 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +16 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +27 -31
  44. data/lib/paper_trail_diff/change_attribution.rb +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 -37
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +3 -6
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +1 -2
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +40 -45
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +170 -42
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +20 -31
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +46 -9
  73. data/lib/paper_trail_diff/prepared_record_index.rb +137 -47
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +41 -19
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +7 -17
  84. data/lib/paper_trail_diff/scope_ranking.rb +16 -22
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +4 -3
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +60 -41
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +37 -20
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +3 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +192 -91
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +37 -21
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +32 -0
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +28 -42
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +0 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +11 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +0 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +36 -2
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +121 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +15 -6
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +9 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +11 -5
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +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 -12
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +0 -2
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +9 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +103 -14
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +9 -12
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +68 -14
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +27 -8
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +0 -2
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -10
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +2 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +37 -14
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -8
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +2 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +111 -52
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +15 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +13 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +28 -6
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -35,9 +35,28 @@ module PaperTrailDiff
35
35
  # : () -> Hash[Array[String], Array[ChangeRow]]
36
36
  def change_rows: () -> Hash[Array[String], Array[ChangeRow]]
37
37
 
38
+ # The analysis of one of `roots`, found from the record itself. The keys
39
+ # are its base class's name and its ID as a string, which a subclass or an
40
+ # integer ID gets wrong when built by hand. Raises KeyError for a record
41
+ # the selection did not load; a deleted root's analysis is in `deleted`.
42
+ # : (untyped) -> Analysis
43
+ def analysis_for: (untyped) -> Analysis
44
+
45
+ # Each root's net changes, keyed as `change_rows` is; the block picks the
46
+ # rows to keep, as for Analysis#net_changes.
47
+ # : () ?{ (ChangeRow) -> boolish } -> Hash[Array[String], Array[NetChange]]
48
+ def net_changes: () ?{ (ChangeRow) -> boolish } -> Hash[Array[String], Array[NetChange]]
49
+
38
50
  # Two elements, not three: `roots` is reached by name so that existing
39
51
  # destructuring keeps working.
40
52
  # : () -> [Hash[Array[String], Analysis], Array[Array[String]]]
41
53
  def to_ary: () -> [ Hash[Array[String], Analysis], Array[Array[String]] ]
54
+
55
+ private
56
+
57
+ # What the block makes of each root's analysis: the roots that still
58
+ # exist, then the deleted ones that have history to report.
59
+ # : [T] () { (Analysis) -> T } -> Hash[Array[String], T]
60
+ def each_root: [T] () { (Analysis) -> T } -> Hash[Array[String], T]
42
61
  end
43
62
  end
@@ -3,8 +3,8 @@
3
3
  module PaperTrailDiff
4
4
  # Selects both populations and checks their shared ceiling before analysis.
5
5
  class ScopedAnalysisBuilder
6
- # : (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
7
- def initialize: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
6
+ # : (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
7
+ def initialize: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
8
8
 
9
9
  # : () -> ScopedAnalysis
10
10
  def call: () -> ScopedAnalysis
@@ -25,7 +25,9 @@ module PaperTrailDiff
25
25
  # window. `where(status: 'published')` selects what is published now, which is
26
26
  # not the same set as what was published while the window was open.
27
27
  class ScopedRootSelection
28
- PAGE_SIZE: ::Integer
28
+ MIN_PAGE_SIZE: ::Integer
29
+
30
+ MAX_PAGE_SIZE: ::Integer
29
31
 
30
32
  # A plain class rather than Data.define, which arrived in Ruby 3.2 while this
31
33
  # gem supports 3.1.
@@ -40,10 +42,11 @@ module PaperTrailDiff
40
42
 
41
43
  # `activity_tree` names the association paths whose changes also select a
42
44
  # root, as an activity analysis reports them. Without one, only a root's
43
- # own versions select it. `version_scope` narrows which of those count,
44
- # as it narrows which are reported.
45
- # : (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
46
- def initialize: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
45
+ # own versions select it. `version_scope` narrows which of either count,
46
+ # as it narrows which are reported. `traversal` names the requested paths,
47
+ # which decide where a window's edges move (see TransactionCut).
48
+ # : (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
49
+ def initialize: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped, ?traversal: AssociationTraversal?) -> void
47
50
 
48
51
  # : () -> Result
49
52
  def call: () -> Result
@@ -54,6 +57,8 @@ module PaperTrailDiff
54
57
 
55
58
  @limit: Integer
56
59
 
60
+ @path_types: Array[String]
61
+
57
62
  @related: AssociationActivitySelection?
58
63
 
59
64
  @scope: untyped
@@ -83,6 +88,13 @@ module PaperTrailDiff
83
88
  # : (Array[String]) -> Result
84
89
  def plucked_selection: (Array[String]) -> Result
85
90
 
91
+ # The candidates the relation's conditions accept. A grouped relation's
92
+ # rows are groups, which a condition on one record cannot decide, and its
93
+ # aggregates read every candidate at once, so it keeps them all: the
94
+ # filter reads each, and the relation groups those that match.
95
+ # : (Array[String]) -> Array[String]
96
+ def relation_members: (Array[String]) -> Array[String]
97
+
86
98
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
87
99
  # rejects an integer key against a string item_id outright. A composite
88
100
  # key names no single attribute, so it has no type and never matches.
@@ -101,10 +113,16 @@ module PaperTrailDiff
101
113
  def missing_ids: () -> Array[String]
102
114
 
103
115
  # Only the versions `version_scope` keeps select a root: one whose versions
104
- # in the window it drops would have nothing to report.
116
+ # in the window it drops would have nothing to report. A version saved
117
+ # just before the window selects its root when TransactionCut moves the
118
+ # root's window back to take it in.
105
119
  # : () -> untyped
106
120
  def window_versions: () -> untyped
107
121
 
122
+ # The filter reads each candidate over the window its analysis will.
123
+ # : (untyped, Integer, AssociationTraversal?) -> HistoricalFilter?
124
+ def historical_filter_for: (untyped, Integer, AssociationTraversal?) -> HistoricalFilter?
125
+
108
126
  # Accepts a model class as readily as a relation: `Article` and
109
127
  # `Article.where(...)` both name a population, and `all` is what makes them
110
128
  # the same kind of thing.
@@ -135,29 +153,34 @@ module PaperTrailDiff
135
153
  # : (Array[untyped]) -> Array[untyped]
136
154
  def selected_records: (Array[untyped]) -> Array[untyped]
137
155
 
156
+ # Pages are read by offset, so under a total order.
138
157
  # : (Array[untyped]) -> untyped
139
158
  def candidate_relation: (Array[untyped]) -> untyped
140
159
 
141
160
  # : (untyped, Integer) -> Array[untyped]
142
161
  def record_page: (untyped, Integer) -> Array[untyped]
143
162
 
144
- # Preserve explicit ordering: SQL Server rejects duplicate ORDER BY columns,
145
- # even when the extra ordering would only have served as a tie-breaker.
146
- # : () -> untyped
147
- def ordered_scope: () -> untyped
148
-
149
163
  # : (Integer) -> Integer
150
164
  def page_limit: (Integer) -> Integer
151
165
 
166
+ # Every page repeats the candidates, a list of ids or the subqueries that
167
+ # find them, and skips the rows read before it, so pages much smaller than
168
+ # the selection read the candidates many times over. More roots than
169
+ # `limit:` raise, so a page never needs more than one past it. A page
170
+ # holds at least 250 rows, for a relation whose joins repeat a record,
171
+ # and at most 2,000: SQL Server compiles a statement with its ids written
172
+ # in, and one that listed 20,000 and returned them all outlasted the
173
+ # adapter's default timeout of 5 seconds.
174
+ # : () -> Integer
175
+ def page_size: () -> Integer
176
+
152
177
  # : (Integer) -> void
153
178
  def reject_oversized!: (Integer) -> void
154
179
 
180
+ # Keyed as Endpoint.identity keys the record, which the analyses use.
155
181
  # : (String) -> Array[String]
156
182
  def identity: (String) -> Array[String]
157
183
 
158
- # : () -> String
159
- def item_type: () -> String
160
-
161
184
  # A relation delegates class methods to its model, so every mutation here,
162
185
  # which drops `.model`, answers the same.
163
186
  # mutant:disable
@@ -41,11 +41,16 @@ module PaperTrailDiff
41
41
  def attributes_for: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
42
42
 
43
43
  # Same exclusions as AR normalization, applied to an already typed state.
44
+ # A state without associations is normalized once at each path: the
45
+ # same state is read again at every boundary it spans.
44
46
  # : (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
45
47
  def from_state: (PreparedRecordState, tree: AssociationTree, path: String, ?incoming: untyped, ?associations: snapshot_associations) -> RecordSnapshot
46
48
 
47
49
  private
48
50
 
51
+ # : (PreparedRecordState, AssociationTree, String, untyped, snapshot_associations) -> RecordSnapshot
52
+ def snapshot_from_state: (PreparedRecordState, AssociationTree, String, untyped, snapshot_associations) -> RecordSnapshot
53
+
49
54
  # The id a live record of the same row reports: one value, or one per
50
55
  # column of a composite key.
51
56
  # : (untyped, PreparedRecordState) -> untyped
@@ -58,6 +63,8 @@ module PaperTrailDiff
58
63
 
59
64
  @ignore_policy: IgnorePolicy
60
65
 
66
+ @leaves: Hash[String, Hash[PreparedRecordState, RecordSnapshot]]
67
+
61
68
  @pool: SnapshotPool
62
69
 
63
70
  @structural_columns: Hash[String, Array[String]]
@@ -0,0 +1,35 @@
1
+ # Generated from lib/paper_trail_diff/stored_json_values.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Reads values in the form JSON history gives them back.
5
+ #
6
+ # A `json` or `jsonb` object column stores a record's attributes as they
7
+ # are, without PaperTrail's attribute serializer, so a `serialize`d value
8
+ # comes back as JSON writes it: keys as strings, and dates, times and
9
+ # symbols inside it as strings, which its type does not cast back.
10
+ # PaperTrail's JSON serializer stores a binary value as `{"value" => bytes}`,
11
+ # which its type does not cast back either. Compared as they are, the live
12
+ # row and every version would differ though nothing was edited. So every
13
+ # side is read in one form: a `serialize`d value as JSON writes it, and a
14
+ # binary value as its bytes. Both leave a value read from history as it is.
15
+ module StoredJsonValues
16
+ SERIALIZED_TYPE: ::String
17
+
18
+ BINARY_TYPE: ::String
19
+
20
+ BINARY_KEYS: untyped
21
+
22
+ # For a model whose history is JSON, which StoredTimePrecision.digits
23
+ # tells: a `json` or `jsonb` object column, or the JSON serializer.
24
+ # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
25
+ def self.apply: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
26
+
27
+ # The attributes with the value of each of this type converted. An
28
+ # adapter's type can be a subclass, as PostgreSQL's `bytea` is of binary.
29
+ # : (untyped, Hash[untyped, untyped], String) { (untyped) -> untyped } -> Hash[untyped, untyped]
30
+ def self.convert: (untyped, Hash[untyped, untyped], String) { (untyped) -> untyped } -> Hash[untyped, untyped]
31
+
32
+ # : (untyped) -> untyped
33
+ def self.bytes: (untyped) -> untyped
34
+ end
35
+ end
@@ -19,18 +19,32 @@ module PaperTrailDiff
19
19
  # Fractional digits a model's history keeps for times, or nil when the
20
20
  # history is stored losslessly.
21
21
  # : (untyped) -> Integer?
22
- def self?.digits: (untyped) -> Integer?
22
+ def self.digits: (untyped) -> Integer?
23
23
 
24
24
  # : (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
25
- def self?.apply: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
25
+ def self.apply: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
26
26
 
27
+ # From nine digits on, the step is one nanosecond or a fraction of one, so
28
+ # nothing is cut.
27
29
  # : (untyped, Integer) -> untyped
28
- def self?.truncate: (untyped, Integer) -> untyped
30
+ def self.truncate: (untyped, Integer) -> untyped
29
31
 
30
32
  # : (untyped) -> bool
31
- def self?.json_history?: (untyped) -> bool
33
+ def self.json_history?: (untyped) -> bool
32
34
 
35
+ # Whether the version table keeps this column as `json` or `jsonb`, which
36
+ # PaperTrail writes without its serializer.
37
+ # : (untyped, String) -> bool
38
+ def self.json_column?: (untyped, String) -> bool
39
+
40
+ # mutant:disable - Every mutation that survives here reads the same
41
+ # constant another way: from this module rather than Object, or with `::`.
42
+ # : () -> Integer
43
+ def self.json_time_precision: () -> Integer
44
+
45
+ # Whether PaperTrail writes history with its JSON serializer.
46
+ # mutant:disable - As for json_time_precision.
33
47
  # : () -> bool
34
- def self?.json_serializer?: () -> bool
48
+ def self.json_serializer?: () -> bool
35
49
  end
36
50
  end
@@ -0,0 +1,13 @@
1
+ # Generated from lib/paper_trail_diff/stored_values.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Reads a model's attribute values in the one form every account of them
5
+ # shares: a version decoded from history, the current row, and the changes
6
+ # a version recorded. Each would otherwise differ where nothing was edited.
7
+ # TimeOfDay puts a time of day on one date, and for JSON history,
8
+ # StoredJsonValues and StoredTimePrecision read values as JSON stored them.
9
+ module StoredValues
10
+ # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
11
+ def self.apply: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
12
+ end
13
+ end
@@ -3,52 +3,141 @@
3
3
  module PaperTrailDiff
4
4
  # Internal helpers for isolating and serializing values held by result objects.
5
5
  module Support
6
+ # Ids per statement, for the queries that list them in slices. SQL Server
7
+ # compiles every statement afresh, since its ids are written into it, in
8
+ # time that grows with their number; fewer statements than this cost more
9
+ # than they save.
10
+ IDS_PER_STATEMENT: ::Integer
11
+
12
+ # PaperTrail's YAML serializer stores a `time` column's value as this
13
+ # wrapper, which PaperTrail 16 and 17 decode by reading its `@time`. Only
14
+ # some zone-aware times are stored with one, as a TimeWithZone's fields
15
+ # under the wrapper's tag; any other wraps its time, and decodes as nil.
16
+ TIME_VALUE: ::String
17
+
18
+ # The date a database gives a time of day it reads back.
19
+ TIME_OF_DAY_DATE: Hash[Symbol, Integer]
20
+
21
+ # Answers a question about `value` once for each Active Record class, in
22
+ # `answers`: its respond_to? also looks through the instance's attributes,
23
+ # which costs more than most of what reading a version does, and every
24
+ # instance of a model answers alike, since this gem reads versions with
25
+ # all their columns. Anything else is asked each time.
26
+ # : [T] (Hash[untyped, T], untyped) { (untyped) -> T } -> T
27
+ def self.per_model: [T] (Hash[untyped, T], untyped) { (untyped) -> T } -> T
28
+
29
+ # Stored attributes or changes ready for PaperTrail to decode: keyed by
30
+ # name, with each time of day unwrapped, which then decodes as any value
31
+ # does. A change's values are a pair.
32
+ # : (Hash[untyped, untyped]) -> Hash[String, untyped]
33
+ def self.decodable: (Hash[untyped, untyped]) -> Hash[String, untyped]
34
+
35
+ # : (untyped) -> untyped
36
+ def self.unwrapped_time: (untyped) -> untyped
37
+
38
+ # The time a stored wrapper holds -- the one it wraps, or the `@time`
39
+ # PaperTrail reads -- on 2000-01-01, as the database keeps a time of day.
40
+ # Active Record keeps the date of a time assigned in memory, which
41
+ # PaperTrail stores, but the row holds only the time.
42
+ # : (untyped) -> untyped
43
+ def self.recorded_time: (untyped) -> untyped
44
+
45
+ # PaperTrail's `reify`, with each time of day its version recorded.
46
+ # : (untyped, **untyped) -> untyped
47
+ def self.reify: (untyped, **untyped) -> untyped
48
+
49
+ # A record PaperTrail rebuilt, with each time of day assigned from the
50
+ # version it was rebuilt from, which PaperTrail can decode as nil. PaperTrail
51
+ # assigns stored attributes after building the record and links it to
52
+ # that version, PT-AT's members too, so this assigns what PaperTrail would
53
+ # if it unwrapped the value. Only a version whose stored text names the
54
+ # wrapper is decoded again; any other record is returned as it is.
55
+ # : [T] (T) -> T
56
+ def self.with_recorded_times: [T] (T) -> T
57
+
6
58
  # : (untyped) -> untyped
7
- def self?.immutable_copy: (untyped) -> untyped
59
+ def self.rebuilt_from: (untyped) -> untyped
60
+
61
+ # As PaperTrail assigns a stored attribute.
62
+ # : (untyped, String, untyped) -> void
63
+ def self.assign_recorded: (untyped, String, untyped) -> void
64
+
65
+ # : (untyped) -> untyped
66
+ def self.immutable_copy: (untyped) -> untyped
8
67
 
9
68
  # : (Hash[untyped, untyped]) -> Hash[untyped, untyped]
10
- def self?.immutable_hash: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
69
+ def self.immutable_hash: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
11
70
 
12
71
  # : (untyped) -> untyped
13
- def self?.serialize: (untyped) -> untyped
72
+ def self.serialize: (untyped) -> untyped
14
73
 
15
74
  # Records sort by type first so that mixed id types stay comparable, then
16
75
  # naturally within one type. Ordering by the printed form instead would put
17
76
  # id 10 before id 2, which is deterministic but reads as unsorted wherever a
18
77
  # result is rendered.
19
78
  # : (untyped, untyped) -> Array[untyped]
20
- def self?.sortable_identity: (untyped, untyped) -> Array[untyped]
79
+ def self.sortable_identity: (untyped, untyped) -> Array[untyped]
80
+
81
+ # Which loaded row a version or record is, across the lookups of a call:
82
+ # by its class's name rather than the class, so a row still matches after
83
+ # its class is reloaded.
84
+ # : (untyped) -> Array[untyped]
85
+ def self.row_key: (untyped) -> Array[untyped]
86
+
87
+ # Which record a model and id name, as Endpoint.identity reads a record:
88
+ # by its base class, so a subclass and its base name the same row.
89
+ # : (untyped, untyped) -> Array[String]
90
+ def self.record_identity: (untyped, untyped) -> Array[String]
91
+
92
+ # Only quoting helpers are needed where this is used, so the model's
93
+ # connection is borrowed for the block rather than checked out
94
+ # permanently, which Active Record 7.2 and newer can deprecate. Active
95
+ # Record 7.1 has no `with_connection` and reaches the same connection
96
+ # through the accessor.
97
+ # : [T] (untyped) { (untyped) -> T } -> T
98
+ def self.with_connection: [T] (untyped) { (untyped) -> T } -> T
99
+
100
+ # A constant by its full name, such as a model's or one of Active
101
+ # Record's, untyped: Active Record and the models ship no signatures. Any
102
+ # spelling of the lookup finds the same constant.
103
+ # mutant:disable
104
+ # : (String) -> untyped
105
+ def self.constant: (String) -> untyped
106
+
107
+ # Arel, which ships no signatures either.
108
+ # : () -> untyped
109
+ def self.arel: () -> untyped
21
110
 
22
111
  # : (untyped) -> Array[untyped]
23
- def self?.chronological_version_key: (untyped) -> Array[untyped]
112
+ def self.chronological_version_key: (untyped) -> Array[untyped]
24
113
 
25
114
  # : (untyped, untyped) -> Array[untyped]
26
- def self?.version_key: (untyped, untyped) -> Array[untyped]
115
+ def self.version_key: (untyped, untyped) -> Array[untyped]
27
116
 
28
117
  # Ordering falls back to the id whenever timestamps tie, which recovers the
29
118
  # real order only while ids increase with insertion. An autoincrement id
30
119
  # does; a UUID does not, so a tie between UUID-keyed versions is genuinely
31
120
  # unorderable and any timeline built from it would be fiction.
32
121
  # : (Array[untyped]) -> Array[untyped]
33
- def self?.chronological_sort: (Array[untyped]) -> Array[untyped]
122
+ def self.chronological_sort: (Array[untyped]) -> Array[untyped]
34
123
 
35
124
  # : (Array[untyped]) -> Array[untyped]?
36
- def self?.ambiguous_pair: (Array[untyped]) -> Array[untyped]?
125
+ def self.ambiguous_pair: (Array[untyped]) -> Array[untyped]?
37
126
 
38
127
  # Ids order versions saved in one instant only when they count up in one
39
128
  # table. Two version tables count separately, so ids there say nothing.
40
129
  # : (untyped, untyped) -> bool
41
- def self?.orderable_tie?: (untyped, untyped) -> bool
130
+ def self.orderable_tie?: (untyped, untyped) -> bool
42
131
 
43
132
  # : (untyped) -> untyped
44
- def self?.version_table: (untyped) -> untyped
133
+ def self.version_table: (untyped) -> untyped
45
134
 
46
135
  # Versions sharing a timestamp, whether or not their ids order them. PT-AT
47
136
  # indexes association membership per version but resolves it by timestamp,
48
137
  # so association state cannot be told apart across such a pair even when the
49
138
  # scalar sequence is perfectly recoverable.
50
139
  # : (Array[untyped]) -> Array[untyped]?
51
- def self?.tied_timestamp_pair: (Array[untyped]) -> Array[untyped]?
140
+ def self.tied_timestamp_pair: (Array[untyped]) -> Array[untyped]?
52
141
 
53
142
  # Whether a model records history at all.
54
143
  #
@@ -59,37 +148,45 @@ module PaperTrailDiff
59
148
  # distinguish the two, which is why this lives in one place: the predicate is
60
149
  # easy to write in a form that looks right and always answers true.
61
150
  # : (untyped) -> bool
62
- def self?.versioned?: (untyped) -> bool
151
+ def self.versioned?: (untyped) -> bool
63
152
 
64
153
  # `versions.item_id` is often a string column -- PaperTrail's setup for UUID
65
154
  # keys -- while the model's own key is an integer. An id read from history
66
155
  # is cast to the key's type, or the same record read once from history and
67
156
  # once from its live row would count as two.
68
157
  # : (untyped, untyped) -> untyped
69
- def self?.record_id: (untyped, untyped) -> untyped
158
+ def self.record_id: (untyped, untyped) -> untyped
159
+
160
+ # A relation's limit and offset as Active Record writes them into SQL.
161
+ # Before 8.1 it keeps a limit as given, as every version keeps an offset,
162
+ # so either may be a String, as request parameters are.
163
+ # : (untyped) -> Integer?
164
+ def self.limit: (untyped) -> Integer?
165
+
166
+ # : (untyped) -> Integer
167
+ def self.offset: (untyped) -> Integer
70
168
 
71
169
  # : (untyped) -> bool
72
- def self?.sequential_id?: (untyped) -> bool
170
+ def self.sequential_id?: (untyped) -> bool
73
171
 
74
172
  # : (Array[untyped]) -> String
75
- def self?.ambiguous_message: (Array[untyped]) -> String
173
+ def self.ambiguous_message: (Array[untyped]) -> String
76
174
 
77
175
  # : (untyped, untyped) -> Integer
78
- def self?.compare_versions: (untyped, untyped) -> Integer
176
+ def self.compare_versions: (untyped, untyped) -> Integer
79
177
 
80
178
  # : (String, String | Symbol) -> String
81
- def self?.association_path: (String, String | Symbol) -> String
179
+ def self.association_path: (String, String | Symbol) -> String
82
180
 
181
+ # Groups of one name are joined: their ids, and their owners where both
182
+ # know some. A group that knows none has no :owners key.
83
183
  # : (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
84
- def self?.merge_record_groups: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
184
+ def self.merge_record_groups: (Hash[String, Hash[Symbol, untyped]], Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
85
185
 
86
186
  # : (untyped) -> untyped
87
- def self?.duplicate_and_freeze: (untyped) -> untyped
88
-
89
- # : (Hash[String, Array[untyped]]?, Hash[String, Array[untyped]]?) -> Hash[String, Array[untyped]]?
90
- def self?.merge_record_owners: (Hash[String, Array[untyped]]?, Hash[String, Array[untyped]]?) -> Hash[String, Array[untyped]]?
187
+ def self.duplicate_and_freeze: (untyped) -> untyped
91
188
 
92
189
  # : (untyped) -> bool
93
- def self?.paper_trail_diff_value?: (untyped) -> bool
190
+ def self.paper_trail_diff_value?: (untyped) -> bool
94
191
  end
95
192
  end
@@ -0,0 +1,21 @@
1
+ # Generated from lib/paper_trail_diff/time_of_day.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Reads every value of a `time` column on 2000-01-01, in its own zone.
5
+ #
6
+ # A time column keeps only the time, but Active Record before 8.1 gives a
7
+ # zone-aware one a date two ways: assigned, it falls on 2000-01-01 in the
8
+ # time zone; read from the database, on 2000-01-01 in UTC. A version rebuilt
9
+ # by assignment and the row read for the same time could then hold it a day
10
+ # apart, east of UTC in the morning and west of it in the evening, and
11
+ # compare as a change. Every side is read the way Active Record 8.1 reads
12
+ # both, which leaves a value already on that date as it is.
13
+ module TimeOfDay
14
+ # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
15
+ def self.apply: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
16
+
17
+ # The model's `time` columns, which a model keeps as it was defined.
18
+ # : (untyped) -> Array[String]
19
+ def self.columns: (untyped) -> Array[String]
20
+ end
21
+ end
@@ -1,15 +1,17 @@
1
1
  # Generated from lib/paper_trail_diff/time_range.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Validates and applies a finite wall-clock range without loading model state.
4
+ # Validates and applies a wall-clock range without loading model state.
5
5
  #
6
6
  # A Date is a whole day and a String a local time, both in Time.zone, as
7
7
  # Rails reads them, or in UTC without one: never the server's own zone. An
8
- # inclusive Date end runs through that day.
8
+ # inclusive Date end runs through that day. An endless range has no end:
9
+ # it runs through every version saved since it began, whatever the clock
10
+ # that dated them read, as a report through the current state does.
9
11
  class TimeRange
10
12
  attr_reader begin_time: Time
11
13
 
12
- attr_reader end_time: Time
14
+ attr_reader end_time: Time?
13
15
 
14
16
  # : (untyped) -> void
15
17
  def initialize: (untyped) -> void
@@ -23,10 +25,12 @@ module PaperTrailDiff
23
25
  # : (untyped) -> untyped
24
26
  def scope: (untyped) -> untyped
25
27
 
26
- # The window as a Ruby range, its end included or left out as given.
27
- # : () -> Range[Time]
28
- def to_range: () -> Range[Time]
28
+ # The window as a Ruby range, its end included or left out as given, or
29
+ # endless.
30
+ # : () -> Range[Time?]
31
+ def to_range: () -> Range[Time?]
29
32
 
33
+ # The versions after the window; none follows an endless one.
30
34
  # : (untyped) -> untyped
31
35
  def trailing_scope: (untyped) -> untyped
32
36
 
@@ -40,8 +44,11 @@ module PaperTrailDiff
40
44
 
41
45
  @exclude_end: bool
42
46
 
43
- # : (untyped) -> untyped
44
- def after_end: (untyped) -> untyped
47
+ # : (untyped, Time) -> untyped
48
+ def after: (untyped, Time) -> untyped
49
+
50
+ # : (untyped, Time) -> untyped
51
+ def after_end: (untyped, Time) -> untyped
45
52
 
46
53
  # : (untyped, boundary: Symbol) -> Time
47
54
  def coerce_time: (untyped, boundary: Symbol) -> Time
@@ -6,8 +6,8 @@ module PaperTrailDiff
6
6
  # : (untyped, time_range: TimeRange, version_scope: untyped, live_endpoint: untyped) -> void
7
7
  def initialize: (untyped, time_range: TimeRange, version_scope: untyped, live_endpoint: untyped) -> void
8
8
 
9
- # : (context_required: bool) -> RootVersionPlan
10
- def select_plan: (context_required: bool) -> RootVersionPlan
9
+ # : (context_required: bool, whole: bool) -> RootVersionPlan
10
+ def select_plan: (context_required: bool, whole: bool) -> RootVersionPlan
11
11
 
12
12
  private
13
13
 
@@ -21,8 +21,5 @@ module PaperTrailDiff
21
21
 
22
22
  # : (untyped) -> untyped
23
23
  def trailing_version: (untyped) -> untyped
24
-
25
- # : (Array[untyped]) -> Array[untyped]
26
- def ordered: (Array[untyped]) -> Array[untyped]
27
24
  end
28
25
  end
@@ -3,8 +3,8 @@
3
3
  module PaperTrailDiff
4
4
  # Selects and compares a chronological slice of a record's version history.
5
5
  class TimelineBuilder
6
- # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
7
- def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
6
+ # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
7
+ def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
8
8
 
9
9
  # : () -> Array[Step]
10
10
  def build: () -> Array[Step]
@@ -15,8 +15,10 @@ module PaperTrailDiff
15
15
 
16
16
  attr_reader time_range: TimeRange?
17
17
 
18
- # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
19
- def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
18
+ # `traversal` names the requested paths, which decide where a window's
19
+ # edges move (see TransactionCut).
20
+ # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
21
+ def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
20
22
 
21
23
  # A record with no versions has no first boundary to resolve, which
22
24
  # is an empty history rather than a bad request. Both endpoints are
@@ -27,9 +29,10 @@ module PaperTrailDiff
27
29
  # A batch may have selected these versions already, in which case reselecting
28
30
  # them per record would undo the batching.
29
31
  # The plan says which pairs of versions become steps, which a filter can
30
- # make different from adjacent pairs of the selected versions.
31
- # : (?context_required: bool) -> RootVersionPlan
32
- def select_plan: (?context_required: bool) -> RootVersionPlan
32
+ # make different from adjacent pairs of the selected versions. A `whole`
33
+ # plan replays every version in the range; see RootVersionSelection.
34
+ # : (?context_required: bool, ?whole: bool) -> RootVersionPlan
35
+ def select_plan: (?context_required: bool, ?whole: bool) -> RootVersionPlan
33
36
 
34
37
  # : () -> bool
35
38
  def time?: () -> bool
@@ -56,10 +59,12 @@ module PaperTrailDiff
56
59
 
57
60
  @to: untyped
58
61
 
62
+ @traversal: AssociationTraversal?
63
+
59
64
  @version_scope: untyped
60
65
 
61
- # : () -> RootVersionPlan
62
- def explicit_plan: () -> RootVersionPlan
66
+ # : (bool) -> RootVersionPlan
67
+ def explicit_plan: (bool) -> RootVersionPlan
63
68
 
64
69
  # : (untyped) -> bool
65
70
  def symbolic?: (untyped) -> bool
@@ -0,0 +1,32 @@
1
+ # Generated from lib/paper_trail_diff/total_order.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # A relation's order, completed by its primary key. Reading a relation by
5
+ # offset holds only under a total order: a database may return rows that tie
6
+ # in a different order for each query, so that pages read some records twice
7
+ # and others never.
8
+ module TotalOrder
9
+ # The relation sorted by its key after its own order, unless that order
10
+ # already sorts by the key. Such an order is kept as given, since SQL
11
+ # Server rejects a column listed twice. So is the order of a relation
12
+ # grouped by anything but the key: each of its rows is a group, which a
13
+ # database sorts only by what it groups or aggregates. A relation answers
14
+ # for its model the key and table name read here.
15
+ # : (untyped) -> untyped
16
+ def self.apply: (untyped) -> untyped
17
+
18
+ # : (untyped) -> bool
19
+ def self.grouped_by_other?: (untyped) -> bool
20
+
21
+ # An Arel order or group names its column; SQL text, or the name a group
22
+ # may be given as, is read by key_in_sql?.
23
+ # : (untyped, untyped) -> bool
24
+ def self.key?: (untyped, untyped) -> bool
25
+
26
+ # Whether SQL text names the key, alone or after its table's name. That
27
+ # also finds a key the text only uses, as in `LENGTH(id)`, which then goes
28
+ # without the tie-breaker, but it misses no sort by the key.
29
+ # : (String, untyped) -> bool
30
+ def self.key_in_sql?: (String, untyped) -> bool
31
+ end
32
+ end