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
@@ -30,22 +30,26 @@ module PaperTrailDiff
30
30
 
31
31
  # Builds activity steps while retaining root snapshots for combined analysis.
32
32
  class ActivityHistoryBuilder
33
- #: (Array[untyped], Array[ActivityEvent], untyped, ?current: untyped, ?include_step: untyped, ?snapshots: bool) -> void
33
+ # `closing` is the snapshot after the last event when the range closes on
34
+ # the current record. Any other range ends at a root event, or at events
35
+ # after a window whose steps are not reported, so nothing reads it.
36
+ #: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, ?current: untyped, ?include_step: untyped, ?closing: RecordSnapshot?) -> void
34
37
  def initialize( # rubocop:disable Metrics/ParameterLists
35
- root_versions, events, snapshotter, current: nil, include_step: nil, snapshots: false
38
+ root_versions, events, snapshotter, view:, current: nil, include_step: nil, closing: nil
36
39
  )
37
40
  @root_versions = root_versions
38
41
  @events = events
39
42
  @snapshotter = snapshotter
43
+ @view = view
40
44
  @current = current
41
45
  @include_step = include_step
42
- @snapshots = snapshots
46
+ @closing = closing
43
47
  end
44
48
 
45
49
  #: () -> ActivityHistory
46
50
  def call
47
51
  reset
48
- sequence.each { |event, snapshot| consume(event, snapshot) }
52
+ filter.call(sequence) { |event, snapshot, kept| consume(event, snapshot, kept) }
49
53
  ActivityHistory.new(
50
54
  steps: @steps,
51
55
  root_snapshots: @root_snapshots,
@@ -63,7 +67,8 @@ module PaperTrailDiff
63
67
  # @rbs @snapshotter: untyped
64
68
  # @rbs @current: untyped
65
69
  # @rbs @include_step: untyped
66
- # @rbs @snapshots: bool
70
+ # @rbs @view: ActivityView
71
+ # @rbs @closing: RecordSnapshot?
67
72
  # @rbs @steps: Array[ActivityStep]
68
73
  # @rbs @root_snapshots: Hash[Array[untyped], RecordSnapshot?]
69
74
  # @rbs @first_snapshot: RecordSnapshot?
@@ -71,6 +76,7 @@ module PaperTrailDiff
71
76
  # @rbs @selected_last_snapshot: RecordSnapshot?
72
77
  # @rbs @previous_boundary: ActivityBoundary?
73
78
  # @rbs @previous_event: ActivityEvent?
79
+ # @rbs @passed_reported: bool
74
80
 
75
81
  #: () -> void
76
82
  def reset
@@ -82,6 +88,12 @@ module PaperTrailDiff
82
88
  @selected_last_snapshot = nil
83
89
  @previous_boundary = nil
84
90
  @previous_event = nil
91
+ @passed_reported = false
92
+ end
93
+
94
+ #: () -> ActivityTreeFilter
95
+ def filter
96
+ ActivityTreeFilter.new(@events, reported: @include_step, closing: @closing)
85
97
  end
86
98
 
87
99
  #: () -> ActivitySnapshotSequence
@@ -94,17 +106,30 @@ module PaperTrailDiff
94
106
  )
95
107
  end
96
108
 
97
- #: (ActivityEvent, RecordSnapshot?) -> void
98
- def consume(event, snapshot)
109
+ # A left-out event bounds nothing. A reported step it would have opened
110
+ # still moves the reported range's end past it, to the next boundary.
111
+ #: (ActivityEvent, RecordSnapshot?, bool) -> void
112
+ def consume(event, snapshot, kept)
99
113
  capture_first(snapshot)
100
- boundary = ActivityBoundary.from_version(event.version)
114
+ return pass(event) unless kept
115
+
116
+ boundary = ActivityBoundary.from_version(
117
+ event.version, recorded: @view.recorded_attributes(root: event.root?)
118
+ )
101
119
  @root_snapshots[version_key(event.version)] = snapshot if event.root?
102
120
  append_step(boundary, snapshot) if @previous_boundary
121
+ @selected_last_snapshot = snapshot if @passed_reported
122
+ @passed_reported = false
103
123
  @previous_boundary = boundary
104
124
  @previous_event = event
105
125
  @previous_snapshot = snapshot
106
126
  end
107
127
 
128
+ #: (ActivityEvent) -> void
129
+ def pass(event)
130
+ @passed_reported = true if !@include_step || @include_step.call(event)
131
+ end
132
+
108
133
  #: (RecordSnapshot?) -> void
109
134
  def capture_first(snapshot)
110
135
  return if @first_snapshot_seen
@@ -122,7 +147,7 @@ module PaperTrailDiff
122
147
 
123
148
  @steps << ActivityStep.between(
124
149
  from_boundary: previous_boundary, to_boundary: boundary,
125
- from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @snapshots
150
+ from_snapshot: @previous_snapshot, to_snapshot: snapshot, retain: @view.retain?
126
151
  )
127
152
  @selected_last_snapshot = snapshot
128
153
  end
@@ -14,6 +14,8 @@ module PaperTrailDiff
14
14
  Support.chronological_version_key(start_boundary)
15
15
  end
16
16
  @start_time = Endpoint.version?(start_boundary) ? start_boundary.created_at : start_boundary
17
+ # A time has no transaction.
18
+ @opening_transaction = ActivityTransactionGroups.transaction_key(start_boundary)
17
19
  @end_time = Endpoint.version?(end_boundary) ? end_boundary.created_at : end_boundary
18
20
  @end_key = if Endpoint.version?(end_boundary)
19
21
  Support.chronological_version_key(end_boundary)
@@ -26,11 +28,16 @@ module PaperTrailDiff
26
28
  after_start?(version, key) && before_end?(version, key)
27
29
  end
28
30
 
29
- # Narrows an Active Record version relation by timestamp. Exact tie-breaking
30
- # remains in #include? so this works for integer, UUID, and custom version IDs.
31
+ # Narrows an Active Record version relation by timestamp, and to the
32
+ # start's transaction. Exact tie-breaking remains in #include? so this
33
+ # works for integer, UUID, and custom version IDs.
31
34
  #: (untyped) -> untyped
32
35
  def scope(relation)
33
- relation.where(created_at: @start_time..end_time)
36
+ in_time = relation.where(created_at: @start_time..end_time)
37
+ opening = @opening_transaction
38
+ return in_time unless opening
39
+
40
+ in_time.or(relation.where(transaction_id: opening.last))
34
41
  end
35
42
 
36
43
  #: () -> bool
@@ -58,9 +65,17 @@ module PaperTrailDiff
58
65
  # @rbs @start_key: Array[untyped]?
59
66
  # @rbs @start_time: untyped
60
67
  # @rbs @end_key: Array[untyped]?
68
+ # @rbs @opening_transaction: Array[untyped]?
61
69
 
70
+ # A range starting at a version starts before that version's transaction,
71
+ # where PT-AT reads its associations. A version saved earlier in it, such
72
+ # as the child update behind a `touch: true` parent version, is a change
73
+ # inside the range.
62
74
  #: (untyped, Array[untyped]) -> bool
63
75
  def after_start?(version, key)
76
+ opening = @opening_transaction
77
+ return true if opening && ActivityTransactionGroups.transaction_key(version) == opening
78
+
64
79
  start_key = @start_key
65
80
  return key_before_or_equal?(start_key, key) if start_key
66
81
 
@@ -4,14 +4,15 @@
4
4
  module PaperTrailDiff
5
5
  # Advances scalar-only root events while retaining already reconstructed associations.
6
6
  class ActivityRootSnapshotRefresher
7
- #: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped) -> void
7
+ #: (tree: AssociationTree, traversal: AssociationTraversal, normalizer: SnapshotNormalizer, record_after: untyped, changeset: untyped, partial_snapshotter: untyped, ?record_transition: untyped) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
9
  tree:,
10
10
  traversal:,
11
11
  normalizer:,
12
12
  record_after:,
13
13
  changeset:,
14
- partial_snapshotter:
14
+ partial_snapshotter:,
15
+ record_transition: nil
15
16
  )
16
17
  @tree = tree
17
18
  @traversal = traversal
@@ -19,6 +20,7 @@ module PaperTrailDiff
19
20
  @record_after = record_after
20
21
  @changeset = changeset
21
22
  @partial_snapshotter = partial_snapshotter
23
+ @record_transition = record_transition
22
24
  @unsupported_branches = {} #: Hash[String, Array[String]]
23
25
  @relationship_reflections = {} #: Hash[String, Array[untyped]]
24
26
  end
@@ -34,21 +36,23 @@ module PaperTrailDiff
34
36
 
35
37
  version = event.version
36
38
  model_class = RecordedClass.for(version)
37
- return [false, nil] unless same_record?(previous, version)
39
+ return [false, nil] unless same_record?(previous, model_class, version)
38
40
 
39
- changes = @changeset.call(version, model_class)
40
- return [false, nil] unless changes.respond_to?(:each)
41
- return [false, nil] if changes.empty?
41
+ changed = changed_columns(version, model_class)
42
+ return [false, nil] if changed.empty?
43
+
44
+ # A change of STI class can change the associations themselves.
45
+ record = @record_after.call(version)
46
+ return [false, nil] unless record && recorded_class(record) == model_class
42
47
 
43
- branches = branches_to_refresh(model_class, changes)
48
+ branches = branches_to_refresh(model_class, changed)
44
49
  partial = nil #: RecordSnapshot?
45
50
  unless branches.empty?
46
51
  partial = @partial_snapshotter.call(root_endpoint, context_endpoint, branches)
47
52
  end
48
53
  return [false, nil] if !branches.empty? && !partial
49
54
 
50
- attributes = advanced_attributes(previous, version, changes)
51
- return [false, nil] unless attributes
55
+ attributes = @normalizer.attributes_for(record, tree: @tree, path: '')
52
56
 
53
57
  incoming_associations = {} #: snapshot_associations
54
58
  incoming_associations = partial.associations if partial
@@ -75,22 +79,35 @@ module PaperTrailDiff
75
79
  # @rbs @record_after: untyped
76
80
  # @rbs @changeset: untyped
77
81
  # @rbs @partial_snapshotter: untyped
82
+ # @rbs @record_transition: untyped
78
83
  # @rbs @unsupported_branches: Hash[String, Array[String]]
79
84
  # @rbs @relationship_reflections: Hash[String, Array[untyped]]
80
85
 
81
- #: (RecordSnapshot, untyped, untyped) -> snapshot_attributes?
82
- def advanced_attributes(previous, version, changes)
83
- return previous.attributes if changes.empty?
86
+ # The columns the version changed, from its changeset and from the states
87
+ # either side of it. The changeset leaves out columns that `only:` or
88
+ # `ignore:` exclude and keys written without a version, which the states
89
+ # hold.
90
+ #: (untyped, untyped) -> Array[String]
91
+ def changed_columns(version, model_class)
92
+ changes = @changeset.call(version, model_class)
93
+ names = changes.respond_to?(:each_key) ? changes.each_key.map(&:to_s) : [] #: Array[String]
94
+ transition = @record_transition&.call(version)
95
+ return names unless transition
84
96
 
85
- record = @record_after.call(version)
86
- return unless record
97
+ before, after = transition
98
+ names | (before.keys | after.keys).filter_map do |name|
99
+ name.to_s unless before[name] == after[name]
100
+ end
101
+ end
87
102
 
88
- @normalizer.attributes_for(record, tree: @tree, path: '')
103
+ #: (untyped) -> untyped
104
+ def recorded_class(record)
105
+ record.is_a?(PreparedRecordState) ? record.model_class : record.class
89
106
  end
90
107
 
91
- #: (untyped, untyped) -> Array[String]
92
- def branches_to_refresh(model_class, changes)
93
- (unsupported_branches(model_class) + changed_relationship_branches(model_class, changes))
108
+ #: (untyped, Array[String]) -> Array[String]
109
+ def branches_to_refresh(model_class, changed)
110
+ (unsupported_branches(model_class) + changed_relationship_branches(model_class, changed))
94
111
  .uniq
95
112
  .sort
96
113
  .freeze
@@ -122,15 +139,16 @@ module PaperTrailDiff
122
139
  false
123
140
  end
124
141
 
125
- #: (RecordSnapshot, untyped) -> bool
126
- def same_record?(snapshot, version)
127
- identity = Endpoint.identity(version)
128
- snapshot.type.to_s == identity.fetch(0) && snapshot.id.to_s == identity.fetch(1)
142
+ # The snapshot names the record's class, which for an STI subclass is not
143
+ # the base class the version names.
144
+ #: (RecordSnapshot, untyped, untyped) -> bool
145
+ def same_record?(snapshot, model_class, version)
146
+ snapshot.type.to_s == model_class.name.to_s &&
147
+ snapshot.id.to_s == Endpoint.identity(version).fetch(1)
129
148
  end
130
149
 
131
- #: (untyped, untyped) -> Array[String]
132
- def changed_relationship_branches(model_class, changes)
133
- changed = changes.each_key.map(&:to_s)
150
+ #: (untyped, Array[String]) -> Array[String]
151
+ def changed_relationship_branches(model_class, changed)
134
152
  root_relationship_reflections(model_class).filter_map do |reflection|
135
153
  reflection.name.to_s if changed.intersect?(relationship_columns(reflection))
136
154
  end
@@ -2,24 +2,35 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Optional full/partial snapshot operations consumed by the activity sequence.
5
+ # Prepares the snapshot store for an activity build, one root at a time.
6
+ # Before that, it reads the live record a range closes on.
6
7
  class ActivitySnapshotProvider
7
- #: (snapshotter: untyped, refresher: untyped, preparer: untyped, ?activity_index: untyped) -> void
8
- def initialize(snapshotter:, refresher:, preparer:, activity_index: nil)
9
- @activity_index = activity_index
8
+ # `snapshotter` reads a full snapshot with a given history, and `refresher`
9
+ # builds the incremental refresher for one root's snapshots.
10
+ #: (store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
11
+ def initialize(store:, snapshotter:, refresher:)
12
+ @store = store
10
13
  @snapshotter = snapshotter
11
14
  @refresher = refresher
12
- @preparer = preparer
13
15
  end
14
16
 
15
- #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
17
+ # Roots a batch prepared together share its history, so consecutive ones
18
+ # share these snapshots too, and the caches their refresher builds. They
19
+ # are the same for any root with that history, so reusing them depends on
20
+ # nothing but the history.
21
+ #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedActivitySnapshots
16
22
  def prepare(
17
23
  record,
18
24
  root_versions,
19
25
  start_at: root_versions.first.created_at,
20
26
  end_at: root_versions.last.created_at
21
27
  )
22
- @preparer.call(record, root_versions, start_at: start_at, end_at: end_at)
28
+ history = @store.prepare(record, root_versions, start_at: start_at, end_at: end_at)
29
+ last = @last
30
+ return last if last && last.history.equal?(history)
31
+
32
+ @last = PreparedActivitySnapshots.new(history, store: @store, snapshotter: @snapshotter,
33
+ refresher: @refresher)
23
34
  end
24
35
 
25
36
  #: (untyped, untyped) -> RecordSnapshot?
@@ -27,44 +38,73 @@ module PaperTrailDiff
27
38
  @snapshotter.call(root_endpoint, context_endpoint)
28
39
  end
29
40
 
41
+ # @rbs @store: HistoricalSnapshotStore
42
+ # @rbs @snapshotter: untyped
43
+ # @rbs @refresher: untyped
44
+ # @rbs @last: PreparedActivitySnapshots?
45
+ end
46
+
47
+ # One root's full and incremental snapshots during an activity build. Each
48
+ # read passes along the history prepared for this root, so none depends on
49
+ # which root was prepared last.
50
+ class PreparedActivitySnapshots
51
+ attr_reader :history #: PreparedHistory?
52
+
53
+ #: (PreparedHistory?, store: HistoricalSnapshotStore, snapshotter: untyped, refresher: untyped) -> void
54
+ def initialize(history, store:, snapshotter:, refresher:)
55
+ @history = history
56
+ @store = store
57
+ @snapshotter = snapshotter
58
+ @refresher = refresher.call(self)
59
+ end
60
+
61
+ #: () -> PreparedActivityIndex?
62
+ def activity_index
63
+ @history&.activity_index
64
+ end
65
+
66
+ #: (untyped, untyped) -> RecordSnapshot?
67
+ def call(root_endpoint, context_endpoint)
68
+ @snapshotter.call(root_endpoint, context_endpoint, history: @history)
69
+ end
70
+
30
71
  #: (untyped, untyped, RecordSnapshot?, Array[String], event: ActivityEvent, isolated: bool) -> RecordSnapshot?
31
- def refresh( # rubocop:disable Metrics/ParameterLists
32
- root_endpoint,
33
- context_endpoint,
34
- previous_snapshot,
35
- branches,
36
- event:,
37
- isolated:
38
- )
39
- @refresher.call(
40
- root_endpoint,
41
- context_endpoint,
42
- previous_snapshot,
43
- branches,
44
- event: event,
45
- isolated: isolated
46
- )
72
+ def refresh(root_endpoint, context_endpoint, previous_snapshot, branches, event:, isolated:) # rubocop:disable Metrics/ParameterLists
73
+ @refresher.call(root_endpoint, context_endpoint, previous_snapshot, branches,
74
+ event: event, isolated: isolated)
47
75
  end
48
76
 
49
77
  #: (untyped, untyped, RecordSnapshot?, event: ActivityEvent) -> RecordSnapshot?
50
78
  def advance_root(root_endpoint, context_endpoint, previous_snapshot, event:)
51
- @refresher.advance_root(
52
- root_endpoint,
53
- context_endpoint,
54
- previous_snapshot,
55
- event: event
56
- )
79
+ @refresher.advance_root(root_endpoint, context_endpoint, previous_snapshot, event: event)
57
80
  end
58
81
 
59
- #: () -> PreparedActivityIndex?
60
- def activity_index
61
- @activity_index&.call
82
+ # The branches a refresh rebuilds, with this root's history.
83
+ #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer) -> RecordSnapshot?
84
+ def custom(root_endpoint, context_endpoint, tree:, normalizer:)
85
+ @store.custom(root_endpoint, context_endpoint, tree: tree, normalizer: normalizer,
86
+ history: @history)
87
+ end
88
+
89
+ #: (untyped, habtm_version: untyped) -> untyped
90
+ def association_reader(context_version, habtm_version:)
91
+ @store.association_reader(context_version, habtm_version: habtm_version, history: @history)
92
+ end
93
+
94
+ #: (untyped) -> [Hash[untyped, untyped], Hash[untyped, untyped]]?
95
+ def record_transition(version)
96
+ @history&.record_transition(Endpoint.model_class(version), version.item_id, version)
97
+ end
98
+
99
+ #: (untyped, ?direct: bool) -> [bool, untyped]
100
+ def record_after(version, direct: false)
101
+ @history&.record_after(Endpoint.model_class(version), version.item_id, version,
102
+ direct: direct) || [false, nil]
62
103
  end
63
104
 
64
- # @rbs @activity_index: untyped
105
+ # @rbs @store: HistoricalSnapshotStore
65
106
  # @rbs @snapshotter: untyped
66
107
  # @rbs @refresher: untyped
67
- # @rbs @preparer: untyped
68
108
  end
69
109
 
70
110
  # Builds chronological snapshots, refreshing only branches affected by prior events.
@@ -116,7 +156,7 @@ module PaperTrailDiff
116
156
  incremental_root?(previous_event)
117
157
 
118
158
  branches = @transaction_groups.branches_for(previous_event)
119
- return full_snapshot(event) unless branches && @snapshotter.respond_to?(:refresh)
159
+ return full_snapshot(event) unless branches
120
160
 
121
161
  @snapshotter.refresh(
122
162
  root_endpoint(event.version),
@@ -130,8 +170,7 @@ module PaperTrailDiff
130
170
 
131
171
  #: (ActivityEvent) -> bool
132
172
  def incremental_root?(event)
133
- event.root? && @transaction_groups.isolated?(event) &&
134
- @snapshotter.respond_to?(:advance_root)
173
+ event.root? && @transaction_groups.isolated?(event)
135
174
  end
136
175
 
137
176
  #: (ActivityEvent, ActivityEvent, RecordSnapshot?) -> RecordSnapshot?
@@ -83,11 +83,11 @@ module PaperTrailDiff
83
83
 
84
84
  #: (untyped) -> untyped
85
85
  def historical_relation(version_class)
86
- association_class.joins(:version)
87
- .where(foreign_key_name: @reflection.foreign_key)
88
- .where(version_class.table_name => {
89
- item_type: @owner_class.base_class.name, item_id: @owner_ids
90
- })
86
+ VersionTable.joined(association_class, version_class)
87
+ .where(foreign_key_name: @reflection.foreign_key)
88
+ .where(version_class.table_name => {
89
+ item_type: @owner_class.base_class.name, item_id: @owner_ids
90
+ })
91
91
  end
92
92
 
93
93
  #: (untyped, untyped) -> Array[Array[untyped]]