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
@@ -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,6 +25,12 @@ module PaperTrailDiff
23
25
  # : (untyped) -> untyped
24
26
  def scope: (untyped) -> untyped
25
27
 
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?]
32
+
33
+ # The versions after the window; none follows an endless one.
26
34
  # : (untyped) -> untyped
27
35
  def trailing_scope: (untyped) -> untyped
28
36
 
@@ -36,11 +44,11 @@ module PaperTrailDiff
36
44
 
37
45
  @exclude_end: bool
38
46
 
39
- # : (untyped) -> untyped
40
- def after_end: (untyped) -> untyped
47
+ # : (untyped, Time) -> untyped
48
+ def after: (untyped, Time) -> untyped
41
49
 
42
- # : () -> Range[Time]
43
- def query_range: () -> Range[Time]
50
+ # : (untyped, Time) -> untyped
51
+ def after_end: (untyped, Time) -> untyped
44
52
 
45
53
  # : (untyped, boundary: Symbol) -> Time
46
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,12 +3,16 @@
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]
11
11
 
12
+ # The window the range covers once its edges have moved to transactions.
13
+ # : () -> TimeRange?
14
+ def window: () -> TimeRange?
15
+
12
16
  # : () -> Analysis
13
17
  def analyze: () -> Analysis
14
18
 
@@ -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
@@ -14,14 +14,28 @@ module PaperTrailDiff
14
14
  # Only the root's own versions on either side of an edge are consulted:
15
15
  # rows locked by an update keep two transactions of one root from
16
16
  # interleaving, so a transaction holding a root version and crossing the edge
17
- # holds the root's nearest version on one side of it. Each edge is moved from
18
- # where it was asked for, never from where another edge moved, so adjacent
19
- # windows move their shared edge alike.
17
+ # holds the root's nearest version on one side of it. One that saved the root
18
+ # after the edge moves it. One that saved the root only before the edge moves
19
+ # it only when it saved a record of a type on the requested paths after it,
20
+ # which the root's history reads: without one, the root's change is in the
21
+ # earlier window, where its version is, as selecting by a window's versions
22
+ # finds it, and ScopedRootSelection selects the roots such a move brings into
23
+ # a window. Each edge is moved from where it was asked for, never from where
24
+ # another edge moved, so adjacent windows move their shared edge alike.
20
25
  module TransactionCut
21
26
  # One edge of a window. A strict edge keeps versions recorded at its
22
27
  # instant on the left, as an inclusive end does. A plain class rather than
23
28
  # Data.define, which arrived in Ruby 3.2 while this gem supports 3.1.
24
29
  class Edge
30
+ # A window's start, which keeps versions recorded at it on the right.
31
+ # : (TimeRange) -> Edge
32
+ def self.start_of: (TimeRange) -> Edge
33
+
34
+ # A window's end, strict when the window includes it; an endless window
35
+ # has none.
36
+ # : (TimeRange) -> Edge?
37
+ def self.end_of: (TimeRange) -> Edge?
38
+
25
39
  # : (Time, bool) -> void
26
40
  def initialize: (Time, bool) -> void
27
41
 
@@ -31,62 +45,139 @@ module PaperTrailDiff
31
45
  # : (untyped) -> untyped
32
46
  def right: (untyped) -> untyped
33
47
 
34
- # : (untyped, later: bool) -> untyped
35
- def side: (untyped, later: bool) -> untyped
36
-
37
48
  @strict: bool
38
49
 
39
50
  @time: Time
40
51
  end
41
52
 
42
- # Roots per statement: two lookups each stays under SQLite's limit of 500
43
- # terms in a compound SELECT.
44
- SLICE: ::Integer
45
-
46
53
  # The same as `windows` for a batch of roots, keyed by identity.
47
- # : (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
48
- def self.batch_windows: (Array[untyped], TimeRange?) -> Hash[Array[String], TimeRange]
54
+ # : (Array[untyped], TimeRange?, ?traversal: AssociationTraversal?) -> Hash[Array[String], TimeRange]
55
+ def self.batch_windows: (Array[untyped], TimeRange?, ?traversal: AssociationTraversal?) -> Hash[Array[String], TimeRange]
49
56
 
50
57
  # Where history for a batch must be read from: the earliest moved start.
51
58
  # : (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
52
59
  def self.earliest_start: (TimeRange?, Hash[Array[String], TimeRange]) -> Time?
53
60
 
54
61
  # The windows that move, keyed by root id. A root missing from the result
55
- # keeps the window as asked.
56
- # : (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
57
- def self.windows: (untyped, Array[untyped], TimeRange) -> Hash[String, TimeRange]
62
+ # keeps the window as asked. `traversal` names the requested paths.
63
+ # `records` may be ids. Each move is reported unless `report` is false,
64
+ # for a reader that looks before the analysis that reports them.
65
+ # : (untyped, Array[untyped], TimeRange, ?traversal: AssociationTraversal?, ?report: bool) -> Hash[String, TimeRange]
66
+ def self.windows: (untyped, Array[untyped], TimeRange, ?traversal: AssociationTraversal?, ?report: bool) -> Hash[String, TimeRange]
67
+
68
+ # Reads the windows of `model_class` ids for a range, unreported.
69
+ # : (untyped, AssociationTraversal?) -> ^(Array[String], TimeRange) -> Hash[String, TimeRange]
70
+ def self.reader: (untyped, AssociationTraversal?) -> ^(Array[String], TimeRange) -> Hash[String, TimeRange]
71
+
72
+ # A transaction holds its rows only while it runs, so in history as an
73
+ # application saves it an edge moves by moments. A longer move means a
74
+ # long transaction or rewritten times, which only the application can
75
+ # judge, so each move is reported rather than logged or refused.
76
+ # : (untyped, String, TimeRange, TimeRange) -> void
77
+ def self.report_move: (untyped, String, TimeRange, TimeRange) -> void
78
+
79
+ # The model's versions in a window, and those saved before it in a
80
+ # transaction that saved a record of one of `types` inside it, which
81
+ # moves their root's window back to take them in: the versions that
82
+ # select a root for the window. Without a window, every version does.
83
+ # : (untyped, TimeRange?, Array[String]) -> untyped
84
+ def self.window_versions: (untyped, TimeRange?, Array[String]) -> untyped
85
+
86
+ # : (untyped, untyped, TimeRange, Array[String]) -> untyped
87
+ def self.crossing_versions: (untyped, untyped, TimeRange, Array[String]) -> untyped
58
88
 
59
89
  # : (untyped) -> untyped
60
90
  def self.transaction_versions: (untyped) -> untyped
61
91
 
62
- # Each root's earliest start among its transactions that cross the edge.
63
- # : (untyped, Array[untyped], Edge) -> Hash[String, Time]
64
- def self.moved_edges: (untyped, Array[untyped], Edge) -> Hash[String, Time]
92
+ # : (untyped) -> bool
93
+ def self.transactional?: (untyped) -> bool
94
+
95
+ # Each root's earliest start among its transactions that cross the edge:
96
+ # the one that saved its first version after the edge, which crosses when
97
+ # it began before it, and the one that saved its last version before it,
98
+ # which crosses when it saved a record of one of `types` after it.
99
+ # : (untyped, Array[untyped], Edge, Array[String]) -> Hash[String, Time]
100
+ def self.moved_edges: (untyped, Array[untyped], Edge, Array[String]) -> Hash[String, Time]
101
+
102
+ # For each side of the edge, the roots its transactions hold next to the
103
+ # edge, and where those that cross it began.
104
+ # : (untyped, Array[untyped], Edge, Array[String]) -> Array[[Hash[untyped, Array[String]], Hash[untyped, Time]]]
105
+ def self.crossing: (untyped, Array[untyped], Edge, Array[String]) -> Array[[ Hash[untyped, Array[String]], Hash[untyped, Time] ]]
106
+
107
+ # The roots whose versions next to the edge each transaction holds, those
108
+ # after the edge and those before it.
109
+ # : (untyped, Array[untyped], Edge) -> [Hash[untyped, Array[String]], Hash[untyped, Array[String]]]
110
+ def self.nearest_roots: (untyped, Array[untyped], Edge) -> [ Hash[untyped, Array[String]], Hash[untyped, Array[String]] ]
65
111
 
66
- # The roots whose versions next to the edge each transaction holds.
67
- # : (untyped, Array[untyped], Edge) -> Hash[untyped, Array[String]]
68
- def self.nearest_roots: (untyped, Array[untyped], Edge) -> Hash[untyped, Array[String]]
112
+ # The roots of the rows, by the transaction each row names.
113
+ # : (Array[[String, untyped, bool]]) -> Hash[untyped, Array[String]]
114
+ def self.by_transaction: (Array[[ String, untyped, bool ]]) -> Hash[untyped, Array[String]]
69
115
 
70
116
  # Each root's nearest versions on either side of an edge, as [id,
71
- # transaction] pairs; versions tied at the nearest instant are all kept.
72
- # One indexed lookup per root and side, where a single query over the
73
- # roots would read every version before the edge. The lookups are written
74
- # once with the root's id left open, as building a relation for each root
75
- # costs more than the query. Rows read as SQL text come back as the adapter
76
- # returns them, so the transaction is cast as the grouped query's keys are.
77
- # : (untyped, Array[untyped], Edge) -> Array[[String, untyped]]
78
- def self.nearest: (untyped, Array[untyped], Edge) -> Array[[ String, untyped ]]
79
-
80
- # Both sides' lookups for a root whose id is each `?`.
81
- # : (untyped, Edge) -> String
82
- def self.nearest_lookups: (untyped, Edge) -> String
83
-
84
- # : (untyped, Edge, bool) -> String
85
- def self.nearest_lookup: (untyped, Edge, bool) -> String
86
-
87
- # Where each transaction that has versions on both sides of the edge began.
88
- # : (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
89
- def self.crossing_starts: (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
117
+ # transaction, after the edge] rows; versions tied at the nearest instant
118
+ # are all kept. One statement per slice: a grouped pass over the roots'
119
+ # versions finds both instants, and a join reads the versions saved at
120
+ # either. A lookup per root, joined by UNION ALL, took SQL Server about a
121
+ # second per 200 roots to compile. Rows read without a model come back as
122
+ # the adapter returns them, so the transaction is cast as the grouped
123
+ # query's keys are.
124
+ #
125
+ # The ids go to the adapter as bound parameters. Written into the
126
+ # statement, they made each slice's text new to SQL Server, which compiled
127
+ # it again, at about 0.05 ms per id.
128
+ # : (untyped, Array[untyped], Edge) -> Array[[String, untyped, bool]]
129
+ def self.nearest: (untyped, Array[untyped], Edge) -> Array[[ String, untyped, bool ]]
130
+
131
+ # The roots' versions saved in a transaction at either nearest instant,
132
+ # each with whether it is the one after the edge.
133
+ # : (untyped, Array[untyped], Edge) -> untyped
134
+ def self.nearest_query: (untyped, Array[untyped], Edge) -> untyped
135
+
136
+ # 1 for a version saved at the instant after the edge, 0 for one before.
137
+ # Only the 1 is read (see after_edge?), so another value or alias, or none,
138
+ # answers the same.
139
+ # mutant:disable
140
+ # : (untyped, untyped) -> untyped
141
+ def self.after_edge: (untyped, untyped) -> untyped
142
+
143
+ # Whether after_edge flagged a row as saved after the edge. Adapters
144
+ # return the flag as an Integer or a String, so any spelling that reads
145
+ # only 1 as after answers the same.
146
+ # mutant:disable
147
+ # : (untyped) -> bool
148
+ def self.after_edge?: (untyped) -> bool
149
+
150
+ # Each root's latest instant before the edge and earliest after it, from
151
+ # every version, saved in a transaction or not.
152
+ # : (untyped, Edge) -> untyped
153
+ def self.nearest_instants: (untyped, Edge) -> untyped
154
+
155
+ # The latest or earliest of the times on one side of the edge.
156
+ # : (untyped, untyped, untyped) -> untyped
157
+ def self.side_instant: (untyped, untyped, untyped) -> untyped
158
+
159
+ # The same root's versions saved at either of its instants.
160
+ # : (untyped, untyped) -> untyped
161
+ def self.at_either: (untyped, untyped) -> untyped
162
+
163
+ # Where each transaction that saved a version before the edge began; with
164
+ # `types`, only one that also saved a record of one of them after it.
165
+ # : (untyped, Array[untyped], Edge, ?Array[String]?) -> Hash[untyped, Time]
166
+ def self.crossing_starts: (untyped, Array[untyped], Edge, ?Array[String]?) -> Hash[untyped, Time]
167
+
168
+ # Those of the transactions that saved a version of a record of one of
169
+ # `types` on the edge's later side. A subquery apart from the outer one,
170
+ # rather than an EXISTS correlated with it, so the database finds them
171
+ # once by transaction: SQLite answered the correlated form by scanning
172
+ # every later version of the types for each version before the edge, with
173
+ # the README's indexes 17 s for 450 transactions on 114,000 versions.
174
+ # Only the outer query's transactions are read, so the database can find
175
+ # them by transaction rather than read every later version of the types;
176
+ # the outer query keeps only those anyway, so no spec can tell the
177
+ # mutation that drops them apart.
178
+ # mutant:disable
179
+ # : (untyped, Array[untyped], Edge, Array[String]) -> untyped
180
+ def self.saved_later: (untyped, Array[untyped], Edge, Array[String]) -> untyped
90
181
 
91
182
  # : (TimeRange, Time?, Time?) -> TimeRange
92
183
  def self.moved: (TimeRange, Time?, Time?) -> TimeRange
@@ -34,8 +34,8 @@ module PaperTrailDiff
34
34
  # : (untyped) -> Array[untyped]
35
35
  def self.through_models: (untyped) -> Array[untyped]
36
36
 
37
- # : (tree: AssociationTree, traversal: AssociationTraversal, ?allow_approximate: bool) -> void
38
- def initialize: (tree: AssociationTree, traversal: AssociationTraversal, ?allow_approximate: bool) -> void
37
+ # : (traversal: AssociationTraversal, ?allow_approximate: bool) -> void
38
+ def initialize: (traversal: AssociationTraversal, ?allow_approximate: bool) -> void
39
39
 
40
40
  # : (untyped, historical: bool) -> void
41
41
  def call: (untyped, historical: bool) -> void
@@ -28,7 +28,10 @@ module PaperTrailDiff
28
28
  #
29
29
  # An element that is itself a Hash or Array is reported whole. Saying which
30
30
  # field of which object changed would require pairing before-elements with
31
- # after-elements, and nothing in the value licenses that pairing.
31
+ # after-elements, and nothing in the value licenses that pairing. Elements
32
+ # match with their keys read as strings (NestedComparator.comparable), so
33
+ # `{a: 1}` and `{"a" => 1}` are one element; each is reported as it was
34
+ # given.
32
35
  class ArrayChange
33
36
  attr_reader from: Array[untyped]
34
37
 
@@ -52,6 +55,7 @@ module PaperTrailDiff
52
55
  # : () -> bool
53
56
  def reordered?: () -> bool
54
57
 
58
+ # The same elements in the same order, with keys read as strings.
55
59
  # : () -> bool
56
60
  def empty?: () -> bool
57
61