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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +501 -0
- data/QUICKSTART.md +21 -4
- data/README.md +59 -56
- data/docs/architecture.md +32 -11
- data/docs/performance.md +125 -391
- data/docs/reference.md +470 -117
- data/docs/testing.md +83 -7
- data/lib/paper_trail_diff/activity_boundary.rb +83 -26
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
- data/lib/paper_trail_diff/activity_event.rb +41 -10
- data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
- data/lib/paper_trail_diff/activity_history.rb +34 -9
- data/lib/paper_trail_diff/activity_range.rb +18 -3
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
- data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
- data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
- data/lib/paper_trail_diff/activity_view.rb +69 -0
- data/lib/paper_trail_diff/analysis.rb +37 -6
- data/lib/paper_trail_diff/analysis_batch.rb +25 -31
- data/lib/paper_trail_diff/approximate_paths.rb +48 -0
- data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
- data/lib/paper_trail_diff/association_discovery.rb +9 -1
- data/lib/paper_trail_diff/association_key.rb +56 -0
- data/lib/paper_trail_diff/association_traversal.rb +13 -4
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
- data/lib/paper_trail_diff/batch_preload.rb +53 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
- data/lib/paper_trail_diff/change_row.rb +133 -0
- data/lib/paper_trail_diff/collection_comparator.rb +5 -32
- data/lib/paper_trail_diff/configuration.rb +35 -12
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
- data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
- data/lib/paper_trail_diff/deprecation.rb +61 -0
- data/lib/paper_trail_diff/diagnostics.rb +86 -99
- data/lib/paper_trail_diff/endpoint.rb +26 -3
- data/lib/paper_trail_diff/errors.rb +3 -1
- data/lib/paper_trail_diff/fallback_paths.rb +38 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
- data/lib/paper_trail_diff/historical_filter.rb +19 -10
- data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
- data/lib/paper_trail_diff/nested_comparator.rb +19 -18
- data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
- data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
- data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
- data/lib/paper_trail_diff/prepared_history.rb +15 -1
- data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
- data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
- data/lib/paper_trail_diff/read_snapshot.rb +77 -0
- data/lib/paper_trail_diff/root_version_selection.rb +4 -2
- data/lib/paper_trail_diff/scope_condition.rb +157 -32
- data/lib/paper_trail_diff/scope_ranking.rb +23 -14
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
- data/lib/paper_trail_diff/snapshot.rb +16 -1
- data/lib/paper_trail_diff/support.rb +29 -2
- data/lib/paper_trail_diff/time_range.rb +39 -16
- data/lib/paper_trail_diff/timeline_builder.rb +13 -7
- data/lib/paper_trail_diff/timeline_range.rb +9 -1
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
- data/lib/paper_trail_diff/transaction_cut.rb +240 -0
- data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_boundary.rb +41 -10
- data/lib/paper_trail_diff/version_query.rb +34 -10
- data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
- data/lib/paper_trail_diff/version_table.rb +60 -0
- data/lib/paper_trail_diff.rb +101 -57
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
- data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
- data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
- data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
- data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
- data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
- data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
- data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
- data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
- data/sig/generated/paper_trail_diff/errors.rbs +3 -1
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
- data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
- data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
- data/sig/generated/paper_trail_diff/support.rbs +15 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
- data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
- data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
- data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
- data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
- data/sig/generated/paper_trail_diff.rbs +29 -26
- metadata +49 -11
- data/lib/paper_trail_diff/activity_grouping.rb +0 -38
- data/lib/paper_trail_diff/batch_safety.rb +0 -63
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
- data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
- data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
- 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) -> [
|
|
94
|
-
def transition: (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
|
|
95
|
-
# with nil,
|
|
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
|
-
#
|
|
107
|
-
|
|
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
|
-
# :
|
|
111
|
-
|
|
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
|
-
#
|
|
163
|
-
|
|
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
|
-
#
|
|
166
|
-
|
|
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
|
-
#
|
|
45
|
-
|
|
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
|
-
#
|
|
117
|
-
|
|
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
|
-
#
|
|
45
|
-
#
|
|
46
|
-
#
|
|
47
|
-
#
|
|
48
|
-
|
|
49
|
-
|
|
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
|
-
#
|
|
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]) ->
|
|
10
|
-
def prepare: (untyped, Array[untyped]) ->
|
|
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
|
-
|
|
18
|
-
|
|
19
|
-
# : (untyped) -> RecordSnapshot?
|
|
20
|
-
def live_snapshot: (untyped) -> RecordSnapshot?
|
|
30
|
+
@history: PreparedHistory?
|
|
21
31
|
|
|
22
32
|
@live_snapshotter: untyped
|
|
23
33
|
|