paper_trail_diff 0.15.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 (61) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +159 -1
  3. data/README.md +1 -1
  4. data/docs/performance.md +9 -0
  5. data/docs/reference.md +142 -28
  6. data/docs/testing.md +23 -3
  7. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  8. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  9. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  10. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  11. data/lib/paper_trail_diff/activity_timeline_builder.rb +6 -0
  12. data/lib/paper_trail_diff/analysis.rb +25 -6
  13. data/lib/paper_trail_diff/analysis_batch.rb +2 -2
  14. data/lib/paper_trail_diff/batched_root_analyzer.rb +6 -0
  15. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  16. data/lib/paper_trail_diff/deleted_analysis_batch.rb +7 -3
  17. data/lib/paper_trail_diff/deleted_root_filter.rb +30 -8
  18. data/lib/paper_trail_diff/diagnostics.rb +7 -5
  19. data/lib/paper_trail_diff/paper_trail_adapter.rb +96 -59
  20. data/lib/paper_trail_diff/prepared_activity_index.rb +16 -12
  21. data/lib/paper_trail_diff/prepared_history.rb +11 -5
  22. data/lib/paper_trail_diff/prepared_history_loader.rb +1 -3
  23. data/lib/paper_trail_diff/prepared_record_index.rb +6 -2
  24. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  25. data/lib/paper_trail_diff/scope_condition.rb +85 -15
  26. data/lib/paper_trail_diff/scope_ranking.rb +11 -12
  27. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -7
  28. data/lib/paper_trail_diff/scoped_root_selection.rb +11 -4
  29. data/lib/paper_trail_diff/time_range.rb +7 -6
  30. data/lib/paper_trail_diff/timeline_builder.rb +6 -0
  31. data/lib/paper_trail_diff/transaction_cut.rb +100 -41
  32. data/lib/paper_trail_diff/version.rb +1 -1
  33. data/lib/paper_trail_diff/version_boundary.rb +4 -2
  34. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -1
  35. data/lib/paper_trail_diff.rb +7 -5
  36. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  37. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  38. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  39. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  40. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +4 -0
  41. data/sig/generated/paper_trail_diff/analysis.rbs +17 -5
  42. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +4 -0
  43. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  44. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +3 -0
  45. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +11 -3
  46. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +10 -0
  47. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  48. data/sig/generated/paper_trail_diff/prepared_history.rbs +6 -1
  49. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +2 -1
  50. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  51. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -7
  52. data/sig/generated/paper_trail_diff/scope_ranking.rbs +6 -6
  53. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  54. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +8 -3
  55. data/sig/generated/paper_trail_diff/time_range.rbs +4 -3
  56. data/sig/generated/paper_trail_diff/timeline_builder.rbs +4 -0
  57. data/sig/generated/paper_trail_diff/transaction_cut.rbs +46 -14
  58. data/sig/generated/paper_trail_diff/version_boundary.rbs +2 -0
  59. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +3 -0
  60. data/sig/generated/paper_trail_diff.rbs +2 -2
  61. metadata +7 -5
@@ -18,7 +18,7 @@ module PaperTrailDiff
18
18
  # holds the root's nearest version on one side of it. Each edge is moved from
19
19
  # where it was asked for, never from where another edge moved, so adjacent
20
20
  # windows move their shared edge alike.
21
- module TransactionCut
21
+ module TransactionCut # rubocop:disable Metrics/ModuleLength
22
22
  # One edge of a window. A strict edge keeps versions recorded at its
23
23
  # instant on the left, as an inclusive end does. A plain class rather than
24
24
  # Data.define, which arrived in Ruby 3.2 while this gem supports 3.1.
@@ -40,18 +40,14 @@ module PaperTrailDiff
40
40
  @strict ? column.gt(@time) : column.gteq(@time)
41
41
  end
42
42
 
43
- #: (untyped, later: bool) -> untyped
44
- def side(column, later:)
45
- later ? right(column) : left(column)
46
- end
47
-
48
43
  # @rbs @time: Time
49
44
  # @rbs @strict: bool
50
45
  end
51
46
 
52
- # Roots per statement: two lookups each stays under SQLite's limit of 500
53
- # terms in a compound SELECT.
54
- SLICE = 200
47
+ # Roots, or transactions, per statement. SQL Server compiles every
48
+ # statement afresh, since its ids are written into it, in time that grows
49
+ # with their number; fewer statements than this cost more than they save.
50
+ SLICE = 500
55
51
  private_constant :SLICE
56
52
 
57
53
  # The same as `windows` for a batch of roots, keyed by identity.
@@ -85,8 +81,26 @@ module PaperTrailDiff
85
81
 
86
82
  starts = moved_edges(versions, records, Edge.new(range.begin_time, false))
87
83
  ends = moved_edges(versions, records, Edge.new(range.end_time, !range.exclude_end?))
88
- (starts.keys | ends.keys).to_h { |id| [id, moved(range, starts[id], ends[id])] }
84
+ (starts.keys | ends.keys).to_h do |id|
85
+ [id, moved_window(model_class, id, range, starts[id], ends[id])]
86
+ end
87
+ end
88
+
89
+ # A transaction holds its rows only while it runs, so in history as an
90
+ # application saves it an edge moves by moments. A longer move means a
91
+ # long transaction or rewritten times, which only the application can
92
+ # judge, so each move is reported rather than logged or refused.
93
+ #: (untyped, String, TimeRange, Time?, Time?) -> TimeRange
94
+ def self.moved_window(model_class, id, range, start, finish)
95
+ window = moved(range, start, finish)
96
+ Instrumentation.notify(
97
+ 'moved_window',
98
+ item_type: model_class.base_class.name, item_id: id,
99
+ requested: range.to_range, window: window.to_range
100
+ )
101
+ window
89
102
  end
103
+ private_class_method :moved_window
90
104
 
91
105
  #: (untyped) -> untyped
92
106
  def self.transaction_versions(model_class)
@@ -118,56 +132,101 @@ module PaperTrailDiff
118
132
 
119
133
  # Each root's nearest versions on either side of an edge, as [id,
120
134
  # transaction] pairs; versions tied at the nearest instant are all kept.
121
- # One indexed lookup per root and side, where a single query over the
122
- # roots would read every version before the edge. The lookups are written
123
- # once with the root's id left open, as building a relation for each root
124
- # costs more than the query. Rows read as SQL text come back as the adapter
135
+ # One statement per slice: a grouped pass over the roots' versions finds
136
+ # both instants, and a join reads the versions saved at either. A lookup
137
+ # per root, joined by UNION ALL, took SQL Server about a second per 200
138
+ # roots to compile. Rows read without a model come back as the adapter
125
139
  # returns them, so the transaction is cast as the grouped query's keys are.
126
140
  #: (untyped, Array[untyped], Edge) -> Array[[String, untyped]]
127
141
  def self.nearest(versions, records, edge)
128
- lookup = nearest_lookups(versions, edge)
129
- item_id = versions.type_for_attribute('item_id')
130
- lookups = records.map do |record|
131
- versions.sanitize_sql_array([lookup, *Array.new(4, item_id.serialize(record.id))])
132
- end
133
142
  transaction = versions.type_for_attribute('transaction_id')
134
- versions.connection.select_rows(lookups.join(' UNION ALL ')).map do |id, value|
143
+ versions.connection.select_rows(nearest_sql(versions, records, edge)).map do |id, value|
135
144
  [id.to_s, transaction.cast(value)]
136
145
  end
137
146
  end
138
147
  private_class_method :nearest
139
148
 
140
- # Both sides' lookups for a root whose id is each `?`.
141
- #: (untyped, Edge) -> String
142
- def self.nearest_lookups(versions, edge)
143
- own = versions.where("#{versions.quoted_table_name}.item_id = ?")
144
- "#{nearest_lookup(own, edge, false)} UNION ALL #{nearest_lookup(own, edge, true)}"
149
+ # The roots' versions saved in a transaction at either nearest instant.
150
+ #: (untyped, Array[untyped], Edge) -> String
151
+ def self.nearest_sql(versions, records, edge)
152
+ own = versions.where(item_id: records)
153
+ instants = nearest_instants(own, edge)
154
+ own.joins(arel::Nodes::InnerJoin.new(instants, at_either(own.arel_table, instants)))
155
+ .where.not(transaction_id: nil).select(:item_id, :transaction_id).to_sql
145
156
  end
146
- private_class_method :nearest_lookups
157
+ private_class_method :nearest_sql
158
+
159
+ # Each root's latest instant before the edge and earliest after it, from
160
+ # every version, saved in a transaction or not.
161
+ #: (untyped, Edge) -> untyped
162
+ def self.nearest_instants(own, edge)
163
+ table = own.arel_table
164
+ column = table[:created_at]
165
+ before = side_instant(arel::Nodes::Max, edge.left(column), column).as('before_at')
166
+ after = side_instant(arel::Nodes::Min, edge.right(column), column).as('after_at')
167
+ own.group(:item_id).select(table[:item_id], before, after).arel.as('paper_trail_diff_nearest')
168
+ end
169
+ private_class_method :nearest_instants
147
170
 
148
- #: (untyped, Edge, bool) -> String
149
- def self.nearest_lookup(own, edge, later)
150
- column = own.arel_table[:created_at]
151
- instant = own.where(edge.side(column, later: later))
152
- .reorder(created_at: later ? :asc : :desc).limit(1).select(:created_at)
153
- own.where(column.eq(instant.arel)).where.not(transaction_id: nil)
154
- .select(:item_id, :transaction_id).to_sql
171
+ # The latest or earliest of the times on one side of the edge.
172
+ #: (untyped, untyped, untyped) -> untyped
173
+ def self.side_instant(aggregate, side, column)
174
+ aggregate.new([arel::Nodes::Case.new.when(side).then(column)])
175
+ end
176
+ private_class_method :side_instant
177
+
178
+ # The same root's versions saved at either of its instants.
179
+ #: (untyped, untyped) -> untyped
180
+ def self.at_either(table, instants)
181
+ column = table[:created_at]
182
+ at_either = column.eq(instants[:before_at]).or(column.eq(instants[:after_at]))
183
+ arel::Nodes::On.new(table[:item_id].eq(instants[:item_id]).and(at_either))
155
184
  end
156
- private_class_method :nearest_lookup
185
+ private_class_method :at_either
157
186
 
158
187
  # Where each transaction that has versions on both sides of the edge began.
159
188
  #: (untyped, Array[untyped], Edge) -> Hash[untyped, Time]
160
189
  def self.crossing_starts(version_class, transactions, edge)
161
- return {} if transactions.empty?
162
-
163
- column = version_class.arel_table[:created_at]
164
- scope = version_class.where(transaction_id: transactions)
165
- scope.where(edge.left(column))
166
- .where(transaction_id: scope.where(edge.right(column)).select(:transaction_id))
167
- .group(:transaction_id).minimum(:created_at)
190
+ earlier = edge.left(version_class.arel_table[:created_at])
191
+ later = later_version(version_class.arel_table, edge)
192
+ starts = {} #: Hash[untyped, Time]
193
+ transactions.each_slice(SLICE).with_object(starts) do |slice, found|
194
+ crossing = version_class.where(transaction_id: slice).where(earlier).where(later)
195
+ found.merge!(crossing.group(:transaction_id).minimum(:created_at))
196
+ end
168
197
  end
169
198
  private_class_method :crossing_starts
170
199
 
200
+ # Another version of the same transaction on the edge's later side.
201
+ #: (untyped, Edge) -> untyped
202
+ def self.later_version(table, edge)
203
+ other = other_versions(table)
204
+ arel::SelectManager.new.from(other).project('1')
205
+ .where(other[:transaction_id].eq(table[:transaction_id])
206
+ .and(edge.right(other[:created_at])))
207
+ .exists
208
+ end
209
+ private_class_method :later_version
210
+
211
+ # The version table under a second name, for a subquery over it. Any name
212
+ # serves, and SQLite even accepts an empty one other databases refuse, so
213
+ # no spec can tell the mutations apart.
214
+ # mutant:disable
215
+ #: (untyped) -> untyped
216
+ def self.other_versions(table)
217
+ table.alias('paper_trail_diff_crossing_versions')
218
+ end
219
+ private_class_method :other_versions
220
+
221
+ # Arel ships no signatures; see VersionQuery. Any spelling of the constant
222
+ # finds the same module.
223
+ # mutant:disable
224
+ #: () -> untyped
225
+ def self.arel
226
+ Object.const_get(:Arel)
227
+ end
228
+ private_class_method :arel
229
+
171
230
  #: (TimeRange, Time?, Time?) -> TimeRange
172
231
  def self.moved(range, start, finish)
173
232
  begin_time = start || range.begin_time
@@ -2,5 +2,5 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- VERSION = '0.15.0'
5
+ VERSION = '0.16.0'
6
6
  end
@@ -68,10 +68,12 @@ module PaperTrailDiff
68
68
  end
69
69
  private_class_method :version_record?
70
70
 
71
+ # The same row of the same version table. A record or instant is never a
72
+ # version.
71
73
  #: (untyped, untyped) -> bool
72
74
  def same_version?(left, right)
73
- left.class.table_name == right.class.table_name && left.id.to_s == right.id.to_s
75
+ version_record?(left) && version_record?(right) &&
76
+ left.class.table_name == right.class.table_name && left.id.to_s == right.id.to_s
74
77
  end
75
- private_class_method :same_version?
76
78
  end
77
79
  end
@@ -13,9 +13,12 @@ module PaperTrailDiff
13
13
  @fallback_selected = fallback_selected
14
14
  end
15
15
 
16
+ # The read runs in a savepoint, so that a query that fails here leaves a
17
+ # snapshot transaction around it usable: PostgreSQL refuses every later
18
+ # statement of a transaction once one has failed.
16
19
  #: () -> Array[DiagnosticIssue]
17
20
  def call
18
- versions = ordered_range_versions
21
+ versions = @from_version.class.transaction(requires_new: true) { ordered_range_versions }
19
22
  issues = [] #: Array[DiagnosticIssue?]
20
23
  issues << unorderable(versions)
21
24
  issues << tied_timestamps(versions) if @fallback_selected
@@ -110,6 +110,7 @@ require_relative 'paper_trail_diff/activity_snapshot_sequence'
110
110
  require_relative 'paper_trail_diff/activity_tree_filter'
111
111
  require_relative 'paper_trail_diff/activity_history'
112
112
  require_relative 'paper_trail_diff/activity_timeline_builder'
113
+ require_relative 'paper_trail_diff/read_snapshot'
113
114
  require_relative 'paper_trail_diff/paper_trail_adapter'
114
115
 
115
116
  # @rbs!
@@ -369,12 +370,12 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
369
370
  # for every root that changed or whose requested associations did.
370
371
  # Historical windows remain explicit on analyze_scope; this entry point is
371
372
  # deliberately named for a report through now rather than an as-of query.
372
- #: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
373
+ #: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
373
374
  def report( # rubocop:disable Metrics/ParameterLists
374
375
  scope, since:, limit:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES,
375
- snapshots: false, group: nil, include_deleted: false, historical_filter: nil,
376
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, allow_expensive: nil,
377
- recorded_changes: false, allow_approximate: false
376
+ version_scope: nil, snapshots: false, group: nil, include_deleted: false,
377
+ historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
378
+ allow_expensive: nil, recorded_changes: false, allow_approximate: false
378
379
  )
379
380
  # A range here would become the start of another range.
380
381
  if since.nil? || since.is_a?(Range)
@@ -385,7 +386,8 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
385
386
  analyze_scope(
386
387
  scope,
387
388
  within: since..Time.now.utc, limit: limit, associations: associations,
388
- ignore: ignore, activity: true, snapshots: snapshots, group: group,
389
+ ignore: ignore, activity: true, version_scope: version_scope, snapshots: snapshots,
390
+ group: group,
389
391
  include_deleted: include_deleted, historical_filter: historical_filter,
390
392
  max_filter_versions: max_filter_versions, allow_expensive: allow_expensive,
391
393
  recorded_changes: recorded_changes, allow_approximate: allow_approximate
@@ -36,6 +36,19 @@ module PaperTrailDiff
36
36
  # : (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
37
37
  def unsafe_nested_membership_delta?: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
38
38
 
39
+ # A delta replaces a record's attributes and keeps its associations, so an
40
+ # edit to a key one of them follows, such as a comment's `reviewer_id`
41
+ # under `comments.reviewer`, would leave the old target in place. The
42
+ # branch is read again instead.
43
+ # : (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
44
+ def unsafe_owned_relationship_delta?: (Array[Array[untyped]], ActivitySnapshotDelta?) -> bool
45
+
46
+ # The record's own columns that decide what an association of it holds: a
47
+ # belongs_to's key and type, or those of the belongs_to a through starts
48
+ # from. A has_one or has_many follows the record's primary key.
49
+ # : (untyped) -> Array[untyped]
50
+ def owned_keys: (untyped) -> Array[untyped]
51
+
39
52
  # : (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> [untyped, RecordSnapshot?]
40
53
  def route_event_state: (RecordSnapshot, Array[untyped], untyped, ActivitySnapshotDelta?, Array[untyped], SnapshotNormalizer, Array[untyped], ?direct: bool) -> [ untyped, RecordSnapshot? ]
41
54
 
@@ -12,14 +12,28 @@ module PaperTrailDiff
12
12
  # : (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
13
13
  def belongs_to_routes: (untyped, AssociationTree, String, ?path: String) -> Array[Array[untyped]]
14
14
 
15
+ # Whether a has_many through in the tree joins through, or reaches,
16
+ # records of the type. Its membership follows their keys, which a route
17
+ # to the record elsewhere in the tree does not update.
18
+ # : (untyped, AssociationTree, String) -> bool
19
+ def through_part?: (untyped, AssociationTree, String) -> bool
20
+
15
21
  private
16
22
 
17
23
  @belongs_to_routes: Hash[Array[untyped], Array[Array[untyped]]]
18
24
 
19
25
  @collection_routes: Hash[Array[untyped], Array[Array[untyped]]]
20
26
 
27
+ @through_parts: Hash[Array[untyped], bool]
28
+
21
29
  @traversal: AssociationTraversal
22
30
 
31
+ # : (untyped, AssociationTree, String, String) -> bool
32
+ def through_part_below?: (untyped, AssociationTree, String, String) -> bool
33
+
34
+ # : (untyped, String) -> bool
35
+ def through_reaches?: (untyped, String) -> bool
36
+
23
37
  # Timelines interleave event types, so every requested combination is
24
38
  # retained. Model, tree, and path are fixed per adapter, leaving one entry
25
39
  # per selected item type.
@@ -35,6 +35,12 @@ module PaperTrailDiff
35
35
 
36
36
  @route_finder: ActivityEventRouteFinder
37
37
 
38
+ # A through's membership follows the keys of the records it joins through
39
+ # or reaches, which a route to such a record elsewhere in the tree leaves
40
+ # alone, so the branch is read again instead.
41
+ # : (untyped, AssociationTree, Array[Array[untyped]], ActivityEvent, ActivitySnapshotDelta?) -> bool
42
+ def collection_safe?: (untyped, AssociationTree, Array[Array[untyped]], ActivityEvent, ActivitySnapshotDelta?) -> bool
43
+
38
44
  # : (untyped) -> untyped
39
45
  def record_after: (untyped) -> untyped
40
46
 
@@ -3,8 +3,8 @@
3
3
  module PaperTrailDiff
4
4
  # Advances scalar-only root events while retaining already reconstructed associations.
5
5
  class ActivityRootSnapshotRefresher
6
- # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped) -> void
7
- def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped) -> void
6
+ # : (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped) -> void
7
+ def initialize: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped) -> void
8
8
 
9
9
  # : (untyped, untyped, RecordSnapshot?, ActivityEvent) -> [bool, RecordSnapshot?]
10
10
  def call: (untyped, untyped, RecordSnapshot?, ActivityEvent) -> [ bool, RecordSnapshot? ]
@@ -19,6 +19,8 @@ module PaperTrailDiff
19
19
 
20
20
  @record_after: untyped
21
21
 
22
+ @record_transition: untyped
23
+
22
24
  @relationship_reflections: Hash[String, Array[untyped]]
23
25
 
24
26
  @traversal: AssociationTraversal
@@ -27,11 +29,18 @@ module PaperTrailDiff
27
29
 
28
30
  @unsupported_branches: Hash[String, Array[String]]
29
31
 
30
- # : (RecordSnapshot, untyped, untyped) -> snapshot_attributes?
31
- def advanced_attributes: (RecordSnapshot, untyped, untyped) -> snapshot_attributes?
32
-
32
+ # The columns the version changed, from its changeset and from the states
33
+ # either side of it. The changeset leaves out columns that `only:` or
34
+ # `ignore:` exclude and keys written without a version, which the states
35
+ # hold.
33
36
  # : (untyped, untyped) -> Array[String]
34
- def branches_to_refresh: (untyped, untyped) -> Array[String]
37
+ def changed_columns: (untyped, untyped) -> Array[String]
38
+
39
+ # : (untyped) -> untyped
40
+ def recorded_class: (untyped) -> untyped
41
+
42
+ # : (untyped, Array[String]) -> Array[String]
43
+ def branches_to_refresh: (untyped, Array[String]) -> Array[String]
35
44
 
36
45
  # : (untyped) -> Array[String]
37
46
  def unsupported_branches: (untyped) -> Array[String]
@@ -41,11 +50,13 @@ module PaperTrailDiff
41
50
  # : (untyped) -> bool
42
51
  def direct_versioned_reflection?: (untyped) -> bool
43
52
 
44
- # : (RecordSnapshot, untyped) -> bool
45
- def same_record?: (RecordSnapshot, untyped) -> bool
53
+ # The snapshot names the record's class, which for an STI subclass is not
54
+ # the base class the version names.
55
+ # : (RecordSnapshot, untyped, untyped) -> bool
56
+ def same_record?: (RecordSnapshot, untyped, untyped) -> bool
46
57
 
47
- # : (untyped, untyped) -> Array[String]
48
- def changed_relationship_branches: (untyped, untyped) -> Array[String]
58
+ # : (untyped, Array[String]) -> Array[String]
59
+ def changed_relationship_branches: (untyped, Array[String]) -> Array[String]
49
60
 
50
61
  # : (untyped) -> Array[untyped]
51
62
  def root_relationship_reflections: (untyped) -> Array[untyped]
@@ -15,6 +15,10 @@ module PaperTrailDiff
15
15
  # : () -> Array[ActivityStep]
16
16
  def build: () -> Array[ActivityStep]
17
17
 
18
+ # The window the range covers once its edges have moved to transactions.
19
+ # : () -> TimeRange?
20
+ def window: () -> TimeRange?
21
+
18
22
  # Builds the endpoint diff, the root timeline, and the activity from one
19
23
  # activity snapshot pass.
20
24
  # : () -> Analysis
@@ -13,17 +13,29 @@ module PaperTrailDiff
13
13
 
14
14
  attr_reader to_snapshot: RecordSnapshot?
15
15
 
16
+ # The time window the analysis covers, or nil without one. It is the
17
+ # window asked for unless a transaction crossed an edge, which moves the
18
+ # edge back to where that transaction began.
19
+ attr_reader window: Range[Time]?
20
+
16
21
  # The result for a record whose requested history contains no versions,
17
22
  # which is an empty history rather than a failed request. Its snapshots
18
23
  # are nil because no state was read, not because the record was absent:
19
- # reading one would rebuild the whole graph, per record in a batch.
20
- # : () -> Analysis
21
- def self.empty: () -> Analysis
24
+ # reading one would rebuild the whole graph, per record in a batch. Its
25
+ # activity timeline is empty when activity was asked for and nil when not,
26
+ # as a record with versions would have.
27
+ # : (?activity: bool) -> Analysis
28
+ def self.empty: (?activity: bool) -> Analysis
22
29
 
23
30
  # The reconstructed states the diff was taken between. A report that has to
24
31
  # render unchanged columns needs the whole final state, not only what moved.
25
- # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
26
- def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
32
+ # : (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?window: Range[Time]?) -> void
33
+ def initialize: (diff: Diff, timeline: Array[Step], ?activity_timeline: Array[ActivityStep]?, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?window: Range[Time]?) -> void
34
+
35
+ # The same result for the window it was read in, which the caller knows
36
+ # once it has moved the window's edges to transactions.
37
+ # : (TimeRange?) -> Analysis
38
+ def with_window: (TimeRange?) -> Analysis
27
39
 
28
40
  # Every activity step's rows, in time order. Only the activity timeline says
29
41
  # who made each change, so an analysis built without it has no rows to give.
@@ -11,6 +11,10 @@ module PaperTrailDiff
11
11
  # : (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
12
12
  def call: (untyped, RootVersionPlan, ?TimeRange?) -> Analysis
13
13
 
14
+ # The result for a root with nothing to read.
15
+ # : () -> Analysis
16
+ def empty: () -> Analysis
17
+
14
18
  private
15
19
 
16
20
  @activity: bool
@@ -32,6 +32,12 @@ module PaperTrailDiff
32
32
 
33
33
  @tree: AssociationTree
34
34
 
35
+ # A root version's HABTM members include any created earlier in its
36
+ # transaction. A range ending at that version leaves those creations out
37
+ # as events, so the branch is read again there, whatever event led to it.
38
+ # : (untyped, untyped, Array[String]) -> Array[String]
39
+ def with_habtm: (untyped, untyped, Array[String]) -> Array[String]
40
+
35
41
  # : (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [bool, RecordSnapshot?]
36
42
  def incremental_event: (Array[untyped], RecordSnapshot, Array[String], ActivityEvent?, bool) -> [ bool, RecordSnapshot? ]
37
43
 
@@ -13,6 +13,9 @@ module PaperTrailDiff
13
13
 
14
14
  private
15
15
 
16
+ # : (untyped, RootVersionPlan, TimeRange?) -> Analysis
17
+ def analysis_for: (untyped, RootVersionPlan, TimeRange?) -> Analysis
18
+
16
19
  # : (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
17
20
  def with_unavailable: (Hash[Array[String], Analysis]) -> Hash[Array[String], Analysis?]
18
21
 
@@ -6,12 +6,18 @@ module PaperTrailDiff
6
6
  # table, where a destroyed root has no row, so without this a report on one
7
7
  # account's records would include every account's deletions.
8
8
  class DeletedRootFilter
9
+ SLICE: ::Integer
10
+
9
11
  # : (untyped) -> void
10
12
  def initialize: (untyped) -> void
11
13
 
14
+ # nil when the relation's conditions cannot be read.
15
+ # : (untyped) -> DeletedRootFilter?
16
+ def self.readable: (untyped) -> DeletedRootFilter?
17
+
12
18
  # A root whose destroy PaperTrail did not record has no state to test
13
- # and stays, as it has no state to report either. One whose destroy
14
- # recorded no state is left out.
19
+ # and stays, as it has no state to report either, unless the relation
20
+ # selects nothing. One whose destroy recorded no state is left out.
15
21
  # : (Array[Array[String]]) -> Array[Array[String]]
16
22
  def call: (Array[Array[String]]) -> Array[Array[String]]
17
23
 
@@ -32,7 +38,9 @@ module PaperTrailDiff
32
38
  # : (Hash[String, untyped]?) -> bool
33
39
  def selected?: (Hash[String, untyped]?) -> bool
34
40
 
35
- # The state each root held before its latest destroy.
41
+ # The state each root held before its latest destroy, read in slices: a
42
+ # report lists every deleted root it reached, and SQL Server cannot plan an
43
+ # IN list of thousands.
36
44
  # : (Array[String]) -> Hash[String, Hash[String, untyped]?]
37
45
  def destroyed_states: (Array[String]) -> Hash[String, Hash[String, untyped]?]
38
46
 
@@ -46,6 +46,9 @@ module PaperTrailDiff
46
46
  # : (untyped) -> Hash[Symbol, untyped]
47
47
  def model_payload: (untyped) -> Hash[Symbol, untyped]
48
48
 
49
+ # : (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
50
+ def analyze_record: (untyped, from: untyped, to: untyped, within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Analysis
51
+
49
52
  # : (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
50
53
  def analyze_batch: (Array[untyped], within: untyped, activity: bool, version_scope: untyped, view: ActivityView) -> Hash[identity, Analysis]
51
54
 
@@ -54,6 +57,10 @@ module PaperTrailDiff
54
57
  # : (untyped) -> void
55
58
  def check_scope: (untyped) -> void
56
59
 
60
+ # The endpoints of the hash comparisons. Anything else is left for the batch to refuse.
61
+ # : (untyped) -> Array[untyped]
62
+ def comparison_endpoints: (untyped) -> Array[untyped]
63
+
57
64
  # : (Array[comparison_input], preparer: untyped) -> ComparisonBatch
58
65
  def comparison_batch: (Array[comparison_input], preparer: untyped) -> ComparisonBatch
59
66
 
@@ -64,6 +71,9 @@ module PaperTrailDiff
64
71
  # : (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
65
72
  def analyze_deleted: (untyped, Array[Array[String]], Hash[Symbol, untyped]) -> Hash[Array[String], Analysis?]
66
73
 
74
+ # : (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
75
+ def scoped_builder: (untyped, limit: Integer?, within: untyped, activity: bool, version_scope: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, view: ActivityView) -> ScopedAnalysisBuilder
76
+
67
77
  @activity_snapshotter: ActivitySnapshotProvider
68
78
 
69
79
  @association_tree: AssociationTree
@@ -2,9 +2,16 @@
2
2
 
3
3
  module PaperTrailDiff
4
4
  # Shares association event discovery across every root in a prepared graph.
5
+ #
6
+ # The candidates are the records the prepared snapshots can hold: those
7
+ # recorded under an owner from the start onward, and those under it now. A
8
+ # key changed without a version is recorded only by the record's next
9
+ # version, or by the current row, either of which can come after the range,
10
+ # and the snapshots read it from there. ActivityTreeFilter leaves out the
11
+ # events of a candidate that was outside the tree throughout.
5
12
  class PreparedActivityIndex
6
- # : (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
7
- def initialize: (PreparedRecordIndex, Array[untyped], start_at: untyped, end_at: untyped) -> void
13
+ # : (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
14
+ def initialize: (PreparedRecordIndex, Array[untyped], start_at: untyped) -> void
8
15
 
9
16
  # : (untyped, Array[untyped]) -> void
10
17
  def register: (untyped, Array[untyped]) -> void
@@ -32,8 +39,8 @@ module PaperTrailDiff
32
39
  # : (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
33
40
  def child_ids: (untyped, Array[untyped], untyped, ActivityRange) -> Array[untyped]
34
41
 
35
- # The `belongs_to` targets each owner pointed at in the range: at its start
36
- # and after each change inside it, plus the live row at a current end.
42
+ # The `belongs_to` targets each owner pointed at from the range's start
43
+ # onward, plus the live row.
37
44
  # : (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
38
45
  def target_rows: (untyped, Array[untyped], untyped, ActivityRange) -> Array[ActivityTargetCandidateLoader::Row]
39
46
 
@@ -78,10 +78,15 @@ module PaperTrailDiff
78
78
  # saved, so a tag attached earlier in the checkpoint's own transaction is a
79
79
  # member there, unlike other associations, which a version reads as they
80
80
  # were before its transaction. A member created in that transaction has no
81
- # earlier state, so it is read as it was created.
81
+ # earlier state, so it is read as it was created, from its creation on.
82
+ # The checkpoint's membership also stands for earlier points, since the
83
+ # previous root version; the member did not exist at those yet.
82
84
  # : (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
83
85
  def habtm_records: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
84
86
 
87
+ # : (untyped, untyped, untyped, bool) -> untyped
88
+ def habtm_member: (untyped, untyped, untyped, bool) -> untyped
89
+
85
90
  # A has_many through reads its parts unranked, as its query does. Its own
86
91
  # scope applies to each row, and a ranked read then keeps a record reached
87
92
  # twice as one member.
@@ -70,7 +70,8 @@ module PaperTrailDiff
70
70
 
71
71
  # A record created in the boundary's own transaction has no state before
72
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.
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.
74
75
  # : (untyped) -> untyped
75
76
  def record_created_in: (untyped) -> untyped
76
77