paper_trail_diff 0.14.0 → 0.16.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 (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -68,6 +68,13 @@ module PaperTrailDiff
68
68
  # : (untyped) -> untyped
69
69
  def record_before: (untyped) -> untyped
70
70
 
71
+ # A record created in the boundary's own transaction has no state before
72
+ # it, yet a HABTM checkpoint saved later in that transaction records it as
73
+ # a member. Such a member is read as it was created, at a boundary after
74
+ # its creation; before it, the record did not exist yet.
75
+ # : (untyped) -> untyped
76
+ def record_created_in: (untyped) -> untyped
77
+
71
78
  # : (untyped) -> PreparedRecordState?
72
79
  def state_before: (untyped) -> PreparedRecordState?
73
80
 
@@ -90,8 +97,8 @@ module PaperTrailDiff
90
97
  # : (untyped) -> Array[PreparedRecordState]
91
98
  def states_around: (untyped) -> Array[PreparedRecordState]
92
99
 
93
- # : (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
94
- def transition: (untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
100
+ # : (untyped) -> [PreparedRecordState, PreparedRecordState]?
101
+ def transition: (untyped) -> [ PreparedRecordState, PreparedRecordState ]?
95
102
 
96
103
  private
97
104
 
@@ -144,9 +151,15 @@ module PaperTrailDiff
144
151
  # : (untyped, untyped, untyped) -> untyped
145
152
  def record_before: (untyped, untyped, untyped) -> untyped
146
153
 
154
+ # : (untyped, untyped, untyped) -> untyped
155
+ def record_created_in: (untyped, untyped, untyped) -> untyped
156
+
147
157
  # : (untyped, untyped, untyped) -> [bool, PreparedRecordState?]
148
158
  def snapshot_state_before: (untyped, untyped, untyped) -> [ bool, PreparedRecordState? ]
149
159
 
160
+ # Typed as a reified record's attributes are. A JSON or JSONB `object`
161
+ # column stores times and dates as strings, which PaperTrail does not cast
162
+ # back, and the transition is carried into snapshots built from records.
150
163
  # : (untyped, untyped, untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
151
164
  def transition: (untyped, untyped, untyped) -> [ Hash[untyped, untyped], Hash[untyped, untyped] ]?
152
165
 
@@ -173,6 +186,11 @@ module PaperTrailDiff
173
186
 
174
187
  private
175
188
 
189
+ # A model whose records need their own initialization is cast by
190
+ # instantiating it, as reify does.
191
+ # : (PreparedRecordState) -> Hash[untyped, untyped]
192
+ def typed_attributes: (PreparedRecordState) -> Hash[untyped, untyped]
193
+
176
194
  # : (untyped, String) -> bool
177
195
  def generated_reader?: (untyped, String) -> bool
178
196
 
@@ -0,0 +1,43 @@
1
+ # Generated from lib/paper_trail_diff/read_snapshot.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Runs one read's statements inside one database snapshot. Without one, a row
5
+ # that commits between two statements of the read can be seen by one of them
6
+ # and missed by another: an activity read then found a comment whose versions
7
+ # it had not read yet, and raised `KeyError`.
8
+ #
9
+ # PostgreSQL and MySQL (through mysql2 or trilogy), and adapters built on
10
+ # them such as PostGIS, run the read at REPEATABLE READ, which gives every
11
+ # statement of the transaction the same view. Other adapters get no snapshot;
12
+ # docs/reference.md lists them under limitations.
13
+ module ReadSnapshot
14
+ # The adapters whose subclasses take a snapshot, by name, since an
15
+ # application loads only the adapters it uses.
16
+ SNAPSHOT_ADAPTERS: untyped
17
+
18
+ # Yields once. Each connection the values read through gets a snapshot
19
+ # transaction first, unless that connection already has a transaction open:
20
+ # its isolation level belongs to the caller, and this gem cannot change it.
21
+ # A value may be a model class, a relation, a record, or a version. Any
22
+ # other value reads no table and is ignored.
23
+ # : (Array[untyped]) { () -> untyped } -> untyped
24
+ def self?.call: (Array[untyped]) { () -> untyped } -> untyped
25
+
26
+ # : (untyped) -> bool
27
+ def self?.snapshot?: (untyped) -> bool
28
+
29
+ # One class per connection: each read model and its version class, with the
30
+ # repeats through a shared connection dropped. An associated model on
31
+ # another database is not among them, so it is read outside the snapshot.
32
+ # : (Array[untyped]) -> Array[untyped]
33
+ def self?.connection_classes: (Array[untyped]) -> Array[untyped]
34
+
35
+ # The versioned model a value reads from, or nil.
36
+ # : (untyped) -> untyped
37
+ def self?.model_for: (untyped) -> untyped
38
+
39
+ # A version reads the model of its item; a record reads its own class.
40
+ # : (untyped) -> untyped
41
+ def self?.endpoint_model: (untyped) -> untyped
42
+ end
43
+ end
@@ -13,6 +13,8 @@ module PaperTrailDiff
13
13
  # An error is a specification, so it names the way out as well as the wall.
14
14
  # A window ending at the present can never gain a later version, which makes
15
15
  # "write a checkpoint afterwards" impossible advice on its own.
16
+ # A window closes on the current record when it reaches the present, so
17
+ # this is raised only when there is none to read.
16
18
  INCOMPLETE: ::String
17
19
 
18
20
  # : (in_range: Array[untyped], selected: Array[untyped], after_range: untyped, windowed: bool, ?context_required: bool, ?filtered: bool, ?live_endpoint: untyped) -> void
@@ -13,6 +13,9 @@ module PaperTrailDiff
13
13
  # ranking alone.
14
14
  RELATION_VALUES: untyped
15
15
 
16
+ # Relation parts that load or shape rows without choosing them.
17
+ LOADING_VALUES: untyped
18
+
16
19
  # Types whose stored values compare in Ruby as the database compares them,
17
20
  # named rather than referenced so that loading needs no Active Model.
18
21
  VALUE_TYPES: untyped
@@ -47,6 +50,20 @@ module PaperTrailDiff
47
50
  # : (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
48
51
  def self.build: (untyped, ?untyped, ?ranked: bool) -> ScopeCondition?
49
52
 
53
+ # A relation's own where clause, default scope included, read as
54
+ # conditions on stored attributes; nil when it cannot be. Its order,
55
+ # limit, and offset choose a page of current rows rather than membership,
56
+ # and loading or selecting columns changes neither, so they are left out.
57
+ # A single-table subclass's type condition is left to the caller, as for
58
+ # an association. `none` selects nothing, whatever it is chained to.
59
+ # : (untyped, untyped) -> ScopeCondition?
60
+ def self.for_relation: (untyped, untyped) -> ScopeCondition?
61
+
62
+ # A relation `none` built, whose where clause is SQL text. A condition
63
+ # that matches nothing reads no attribute, so it names no model.
64
+ # : () -> ScopeCondition
65
+ def self.nothing: () -> ScopeCondition
66
+
50
67
  # nil when the relation picks its members by conditions alone.
51
68
  # : (untyped, untyped, untyped) -> ScopeRanking?
52
69
  def self.ranking: (untyped, untyped, untyped) -> ScopeRanking?
@@ -71,16 +88,22 @@ module PaperTrailDiff
71
88
  def self.scoped_relation: (untyped, untyped) -> untyped
72
89
 
73
90
  # Some parts, such as the having clause `or` sets, may be present but
74
- # empty.
75
- # : (untyped) -> bool
76
- def self.plain_relation?: (untyped) -> bool
91
+ # empty. `allowed` names the parts that may hold values.
92
+ # : (untyped, Array[Symbol]) -> bool
93
+ def self.plain_relation?: (untyped, Array[Symbol]) -> bool
77
94
 
78
95
  # : (untyped, Array[untyped], ?ScopeRanking?) -> void
79
96
  def initialize: (untyped, Array[untyped], ?ScopeRanking?) -> void
80
97
 
98
+ # SQL admits a row only when its condition is true, not when it is
99
+ # unknown.
81
100
  # : (Hash[String, untyped]) -> bool
82
101
  def matches?: (Hash[String, untyped]) -> bool
83
102
 
103
+ # Whether no record can match, as for a relation `none` built.
104
+ # : () -> bool
105
+ def none?: () -> bool
106
+
84
107
  # The members among records that are each the owner's by key: those that
85
108
  # meet the conditions, then ranked.
86
109
  # : (Array[untyped]) -> Array[untyped]
@@ -91,10 +114,15 @@ module PaperTrailDiff
91
114
  # : (Array[untyped]) -> Array[untyped]
92
115
  def rank: (Array[untyped]) -> Array[untyped]
93
116
 
94
- # SQL compares NULL with nothing, so only an IS NULL test, an equality
95
- # with nil, matches it.
117
+ # SQL's three values: a comparison with NULL is unknown (nil) rather than
118
+ # false, except an IS NULL or IS NOT NULL test, an equality with nil, which
119
+ # is always known. Unknown matters only under NOT, which leaves it
120
+ # unknown where false would become true.
96
121
  COMPARISONS: untyped
97
122
 
123
+ # Comparisons that order values, which read them as ScopeRanking sorts.
124
+ ORDERED: untyped
125
+
98
126
  private
99
127
 
100
128
  @model_class: untyped
@@ -103,12 +131,26 @@ module PaperTrailDiff
103
131
 
104
132
  @ranking: ScopeRanking?
105
133
 
106
- # : (Array[untyped], Hash[String, untyped]) -> bool
107
- def evaluate: (Array[untyped], Hash[String, untyped]) -> bool
134
+ # true, false, or nil for unknown.
135
+ # : (Array[untyped], Hash[String, untyped]) -> bool?
136
+ def evaluate: (Array[untyped], Hash[String, untyped]) -> bool?
137
+
138
+ # False if any part is, otherwise unknown if any part is.
139
+ # : (Array[bool?]) -> bool?
140
+ def all: (Array[bool?]) -> bool?
141
+
142
+ # True if any part is, otherwise unknown if any part is.
143
+ # : (Array[bool?]) -> bool?
144
+ def any: (Array[bool?]) -> bool?
145
+
146
+ # : (bool?) -> bool?
147
+ def negate: (bool?) -> bool?
108
148
 
109
- # The form the database holds, as the scope's own values were cast.
110
- # : (String, Hash[String, untyped]) -> untyped
111
- def stored: (String, Hash[String, untyped]) -> untyped
149
+ # The form the database holds, as the scope's own values were cast. An
150
+ # order reads the value the database sorts by instead: SQL Server holds a
151
+ # time or date in a wrapper that only compares for equality.
152
+ # : (Symbol, String, Hash[String, untyped]) -> untyped
153
+ def stored: (Symbol, String, Hash[String, untyped]) -> untyped
112
154
 
113
155
  # Builds each reflection's condition once per target class.
114
156
  class Cache
@@ -146,6 +188,25 @@ module PaperTrailDiff
146
188
  # : (untyped) -> Array[untyped]
147
189
  def comparison: (untyped) -> Array[untyped]
148
190
 
191
+ RANGES: untyped
192
+
193
+ # A range, as `where(created_at: 1.day.ago..)` writes it, on a column
194
+ # whose values sort in Ruby as the database sorts them.
195
+ # : (untyped) -> Array[untyped]
196
+ def range: (untyped) -> Array[untyped]
197
+
198
+ # : (untyped) -> Array[untyped]
199
+ def between: (untyped) -> Array[untyped]
200
+
201
+ # : (Symbol, untyped, untyped) -> Array[untyped]
202
+ def bound: (Symbol, untyped, untyped) -> Array[untyped]
203
+
204
+ # A bound in the form the database holds, read back as the value the
205
+ # database sorts by. Reading it back unwraps what an adapter wraps.
206
+ # : (String, untyped) -> untyped
207
+ def sort_value: (String, untyped) -> untyped
208
+
209
+ # Whether a value is NULL compares alike on every type.
149
210
  # : (Symbol, untyped) -> Array[untyped]
150
211
  def binary: (Symbol, untyped) -> Array[untyped]
151
212
 
@@ -158,12 +219,17 @@ module PaperTrailDiff
158
219
  def list: (Symbol, untyped, Array[untyped]) -> Array[untyped]
159
220
 
160
221
  # Ruby comparison stands in for SQL only on the record's own column of
161
- # a type both compare alike.
162
- # : (untyped) -> String
163
- def column: (untyped) -> String
222
+ # a type both compare alike. Whether a value is NULL, any column's
223
+ # type compares alike.
224
+ # : (untyped, ?null_test: bool) -> String
225
+ def column: (untyped, ?null_test: bool) -> String
226
+
227
+ # : (String, untyped) -> bool
228
+ def comparable?: (String, untyped) -> bool
164
229
 
165
- # : (String) -> bool
166
- def comparable?: (String) -> bool
230
+ # PostgreSQL's citext is text that compares without regard to case.
231
+ # : (untyped) -> bool
232
+ def exact_text?: (untyped) -> bool
167
233
 
168
234
  # An enum compares the values it stores, which its subtype describes. A
169
235
  # wrapper such as a serialized or encrypted type is none of these.
@@ -13,6 +13,10 @@ module PaperTrailDiff
13
13
 
14
14
  ENUM_TYPE: ::String
15
15
 
16
+ # Rails wraps a time-zone-aware attribute's type, by default every
17
+ # datetime's, in this delegator; the time it stores is the wrapped type's.
18
+ TIME_ZONE_TYPE: ::String
19
+
16
20
  # Integers, booleans and dates sort alike everywhere. Strings follow a
17
21
  # collation, so they are not read.
18
22
  ORDER_TYPES: untyped
@@ -67,6 +71,16 @@ module PaperTrailDiff
67
71
  # : (untyped, String) -> bool
68
72
  def self.orderable?: (untyped, String) -> bool
69
73
 
74
+ # The value the database sorts by, as the column's type casts it. An enum
75
+ # sorts by the integer it stores; other types are compared cast, since an
76
+ # adapter may serialize a time or date as a wrapper, as SQL Server does.
77
+ # : (untyped, String, untyped) -> untyped
78
+ def self.sort_value: (untyped, String, untyped) -> untyped
79
+
80
+ # The type of the value a column stores, under an enum or time zone wrapper.
81
+ # : (untyped) -> untyped
82
+ def self.stored_type: (untyped) -> untyped
83
+
70
84
  # Active Record truncates a time to its column's precision before writing
71
85
  # it, so history holds the stored value when it keeps that many digits.
72
86
  # Times the type stores in UTC sort as the instants they name; local
@@ -107,11 +121,5 @@ module PaperTrailDiff
107
121
  # A time as its seconds, exactly, and a date as its day number.
108
122
  # : (untyped) -> Numeric
109
123
  def number: (untyped) -> Numeric
110
-
111
- # The value the database sorts by, as the key's type casts it. An enum
112
- # sorts by the integer it stores; other types are compared cast, since an
113
- # adapter may serialize a time or date as a wrapper, as SQL Server does.
114
- # : (String, Hash[String, untyped]) -> untyped
115
- def stored: (String, Hash[String, untyped]) -> untyped
116
124
  end
117
125
  end
@@ -29,6 +29,12 @@ module PaperTrailDiff
29
29
  # : (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?]) -> void
30
30
  def initialize: (analyses: Hash[Array[String], Analysis], unreachable: Array[Array[String]], ?roots: Array[untyped], ?deleted: Hash[Array[String], Analysis?]) -> void
31
31
 
32
+ # Each root's change rows, keyed as `analyses` is: the roots that still
33
+ # exist, then the deleted ones that have history to report. A deleted root
34
+ # without destroy history has no rows and is left out.
35
+ # : () -> Hash[Array[String], Array[ChangeRow]]
36
+ def change_rows: () -> Hash[Array[String], Array[ChangeRow]]
37
+
32
38
  # Two elements, not three: `roots` is reached by name so that existing
33
39
  # destructuring keeps working.
34
40
  # : () -> [Hash[Array[String], Analysis], Array[Array[String]]]
@@ -3,16 +3,28 @@
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?) -> 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?) -> 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) -> 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
8
8
 
9
9
  # : () -> ScopedAnalysis
10
10
  def call: () -> ScopedAnalysis
11
11
 
12
+ private
13
+
14
+ # Without the option, the deleted roots are still tested when the
15
+ # relation can be read, so that another selection's are not listed.
16
+ # : (untyped, bool) -> DeletedRootFilter?
17
+ def deleted_filter: (untyped, bool) -> DeletedRootFilter?
18
+
19
+ # : (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
20
+ def analysis: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
21
+
12
22
  @analyzer: untyped
13
23
 
14
24
  @deleted_analyzer: untyped
15
25
 
26
+ @deleted_filter: DeletedRootFilter?
27
+
16
28
  @include_deleted: bool
17
29
 
18
30
  @limit: Integer
@@ -40,9 +40,10 @@ module PaperTrailDiff
40
40
 
41
41
  # `activity_tree` names the association paths whose changes also select a
42
42
  # root, as an activity analysis reports them. Without one, only a root's
43
- # own versions select it.
44
- # : (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
45
- def initialize: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
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
46
47
 
47
48
  # : () -> Result
48
49
  def call: () -> Result
@@ -59,6 +60,8 @@ module PaperTrailDiff
59
60
 
60
61
  @time_range: TimeRange?
61
62
 
63
+ @version_scope: untyped
64
+
62
65
  # Leaves the candidate set in the database. Plucking every root changed in
63
66
  # the window would cost memory and a statement proportional to all activity
64
67
  # in the window -- not to the relation or `limit:` -- so a report on one
@@ -71,6 +74,12 @@ module PaperTrailDiff
71
74
  # : (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
72
75
  def subqueries: (Array[AssociationActivitySelection::source]) -> Array[AssociationActivitySelection::Query]?
73
76
 
77
+ # Which candidates still have a row is asked without the relation's
78
+ # conditions, so that "filtered out" and "no longer exists" stay
79
+ # separable. A filter then reads the history of the relation's records
80
+ # only, whose order and page choose among those that match, and of the
81
+ # deleted ones, which no relation can test. Those it lists, as without a
82
+ # filter, but does not count toward `limit:`.
74
83
  # : (Array[String]) -> Result
75
84
  def plucked_selection: (Array[String]) -> Result
76
85
 
@@ -91,6 +100,8 @@ module PaperTrailDiff
91
100
  # : () -> Array[String]
92
101
  def missing_ids: () -> Array[String]
93
102
 
103
+ # Only the versions `version_scope` keeps select a root: one whose versions
104
+ # in the window it drops would have nothing to report.
94
105
  # : () -> untyped
95
106
  def window_versions: () -> untyped
96
107
 
@@ -113,10 +124,8 @@ module PaperTrailDiff
113
124
  # : () -> Array[String]
114
125
  def versioned_ids: () -> Array[String]
115
126
 
116
- # Which of those candidates still have a row, asked without the relation's
117
- # conditions so that "filtered out" and "no longer exists" stay separable.
118
- # : (Array[String]) -> Array[String]
119
- def live_ids: (Array[String]) -> Array[String]
127
+ # : (untyped, Array[String]) -> Array[String]
128
+ def ids_in: (untyped, Array[String]) -> Array[String]
120
129
 
121
130
  # Deduplicate records rather than adding SQL DISTINCT: an otherwise valid
122
131
  # relation may order by joined columns or select a PostgreSQL json column.
@@ -70,6 +70,14 @@ module PaperTrailDiff
70
70
  # : (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?, membership_preserved: bool) -> AssociationSnapshot
71
71
  def transition_to: (Array[RecordSnapshot], before: RecordSnapshot?, after: RecordSnapshot?, membership_preserved: bool) -> AssociationSnapshot
72
72
 
73
+ # Collections are documented in record type, then ID, order wherever they
74
+ # were read from. Most arrive sorted, so they are checked before sorting.
75
+ # : (Array[RecordSnapshot]) -> Array[RecordSnapshot]
76
+ def ordered: (Array[RecordSnapshot]) -> Array[RecordSnapshot]
77
+
78
+ # : (Array[Array[untyped]]) -> bool
79
+ def sorted?: (Array[Array[untyped]]) -> bool
80
+
73
81
  # : (AssociationSnapshot) -> CollectionTransition?
74
82
  def transition_from: (AssociationSnapshot) -> CollectionTransition?
75
83
 
@@ -12,6 +12,13 @@ module PaperTrailDiff
12
12
  # : (untyped) -> untyped
13
13
  def self?.serialize: (untyped) -> untyped
14
14
 
15
+ # Records sort by type first so that mixed id types stay comparable, then
16
+ # naturally within one type. Ordering by the printed form instead would put
17
+ # id 10 before id 2, which is deterministic but reads as unsorted wherever a
18
+ # result is rendered.
19
+ # : (untyped, untyped) -> Array[untyped]
20
+ def self?.sortable_identity: (untyped, untyped) -> Array[untyped]
21
+
15
22
  # : (untyped) -> Array[untyped]
16
23
  def self?.chronological_version_key: (untyped) -> Array[untyped]
17
24
 
@@ -28,6 +35,14 @@ module PaperTrailDiff
28
35
  # : (Array[untyped]) -> Array[untyped]?
29
36
  def self?.ambiguous_pair: (Array[untyped]) -> Array[untyped]?
30
37
 
38
+ # Ids order versions saved in one instant only when they count up in one
39
+ # table. Two version tables count separately, so ids there say nothing.
40
+ # : (untyped, untyped) -> bool
41
+ def self?.orderable_tie?: (untyped, untyped) -> bool
42
+
43
+ # : (untyped) -> untyped
44
+ def self?.version_table: (untyped) -> untyped
45
+
31
46
  # Versions sharing a timestamp, whether or not their ids order them. PT-AT
32
47
  # indexes association membership per version but resolves it by timestamp,
33
48
  # so association state cannot be told apart across such a pair even when the
@@ -2,6 +2,10 @@
2
2
 
3
3
  module PaperTrailDiff
4
4
  # Validates and applies a finite wall-clock range without loading model state.
5
+ #
6
+ # A Date is a whole day and a String a local time, both in Time.zone, as
7
+ # Rails reads them, or in UTC without one: never the server's own zone. An
8
+ # inclusive Date end runs through that day.
5
9
  class TimeRange
6
10
  attr_reader begin_time: Time
7
11
 
@@ -19,6 +23,10 @@ module PaperTrailDiff
19
23
  # : (untyped) -> untyped
20
24
  def scope: (untyped) -> untyped
21
25
 
26
+ # The window as a Ruby range, its end included or left out as given.
27
+ # : () -> Range[Time]
28
+ def to_range: () -> Range[Time]
29
+
22
30
  # : (untyped) -> untyped
23
31
  def trailing_scope: (untyped) -> untyped
24
32
 
@@ -35,18 +43,25 @@ module PaperTrailDiff
35
43
  # : (untyped) -> untyped
36
44
  def after_end: (untyped) -> untyped
37
45
 
38
- # : () -> Range[Time]
39
- def query_range: () -> Range[Time]
40
-
41
46
  # : (untyped, boundary: Symbol) -> Time
42
47
  def coerce_time: (untyped, boundary: Symbol) -> Time
43
48
 
44
- # Active Support 8.0 and older warn, once per process, that `to_time` will
45
- # change on a zoned time, so read zoned values without it. Every branch
46
- # gives the same instant, so no spec (and no mutation) can tell them apart.
47
- # mutant:disable
48
- # : (untyped) -> Time
49
- def time_value: (untyped) -> Time
49
+ # Anything else names its instant, and `getutc` reads it without
50
+ # `to_time`, which Active Support 8.0 and older warn will change on a
51
+ # zoned time, and without changing the caller's own value as `utc` does.
52
+ # : (untyped) -> untyped
53
+ def time_value: (untyped) -> untyped
54
+
55
+ # An inclusive date end runs through the day: to the next one's start.
56
+ # : (Range[untyped]) -> untyped
57
+ def end_value: (Range[untyped]) -> untyped
58
+
59
+ # A DateTime is a Date too, but names its instant.
60
+ # : (untyped) -> bool
61
+ def calendar_date?: (untyped) -> bool
62
+
63
+ # : () -> untyped
64
+ def zone: () -> untyped
50
65
 
51
66
  # : () -> void
52
67
  def validate_order!: () -> void
@@ -9,6 +9,10 @@ module PaperTrailDiff
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
 
@@ -23,8 +27,8 @@ module PaperTrailDiff
23
27
  # : (RootVersionPlan) -> [Array[Step], RecordSnapshot?, RecordSnapshot?]
24
28
  def compare_history: (RootVersionPlan) -> [ Array[Step], RecordSnapshot?, RecordSnapshot? ]
25
29
 
26
- # : (RootVersionPlan) -> Array[Step]
27
- def build_steps: (RootVersionPlan) -> Array[Step]
30
+ # : (RootVersionPlan, untyped) -> Array[Step]
31
+ def build_steps: (RootVersionPlan, untyped) -> Array[Step]
28
32
 
29
33
  # : () -> [Array[Step], nil, nil]
30
34
  def empty_history: () -> [ Array[Step], nil, nil ]
@@ -73,6 +73,8 @@ module PaperTrailDiff
73
73
  # : () -> untyped
74
74
  def ordered_versions: () -> untyped
75
75
 
76
+ # A batch passes each root the window it already moved to transaction
77
+ # edges; a single record's window is moved here.
76
78
  # : (untyped) -> TimeRange?
77
79
  def build_time_range: (untyped) -> TimeRange?
78
80
 
@@ -1,23 +1,33 @@
1
1
  # Generated from lib/paper_trail_diff/timeline_snapshot_provider.rb with RBS::Inline
2
2
 
3
3
  module PaperTrailDiff
4
- # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
4
+ # Prepares the snapshot store for TimelineBuilder, one root at a time.
5
5
  class TimelineSnapshotProvider
6
6
  # : (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
7
7
  def initialize: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
8
8
 
9
- # : (untyped, Array[untyped]) -> void
10
- def prepare: (untyped, Array[untyped]) -> void
9
+ # : (untyped, Array[untyped]) -> PreparedTimelineSnapshots
10
+ def prepare: (untyped, Array[untyped]) -> PreparedTimelineSnapshots
11
+
12
+ @live_snapshotter: untyped
13
+
14
+ @store: HistoricalSnapshotStore
15
+ end
16
+
17
+ # One root's timeline snapshots, read with the history prepared for it.
18
+ # Adjacent steps share endpoints, so each immutable snapshot, including a
19
+ # nil create state, is kept for this root only and released with it, and
20
+ # batch memory does not retain every reconstructed graph.
21
+ class PreparedTimelineSnapshots
22
+ # : (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
23
+ def initialize: (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
11
24
 
12
25
  # A window closing on current state ends at the live record rather than at a
13
26
  # version, which is the one endpoint no version history can reconstruct.
14
27
  # : (untyped) -> RecordSnapshot?
15
28
  def call: (untyped) -> RecordSnapshot?
16
29
 
17
- private
18
-
19
- # : (untyped) -> RecordSnapshot?
20
- def live_snapshot: (untyped) -> RecordSnapshot?
30
+ @history: PreparedHistory?
21
31
 
22
32
  @live_snapshotter: untyped
23
33