paper_trail_diff 0.17.0 → 0.18.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 (215) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +663 -0
  3. data/QUICKSTART.md +12 -14
  4. data/README.md +32 -30
  5. data/docs/architecture.md +65 -29
  6. data/docs/performance.md +161 -46
  7. data/docs/reference.md +495 -394
  8. data/docs/testing.md +9 -15
  9. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +42 -9
  10. data/lib/paper_trail_diff/activity_boundary.rb +15 -6
  11. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +91 -18
  12. data/lib/paper_trail_diff/activity_collection_event_applier.rb +14 -15
  13. data/lib/paper_trail_diff/activity_collection_record_updater.rb +18 -8
  14. data/lib/paper_trail_diff/activity_collection_route_updater.rb +12 -25
  15. data/lib/paper_trail_diff/activity_event.rb +53 -34
  16. data/lib/paper_trail_diff/activity_event_record_normalizer.rb +12 -26
  17. data/lib/paper_trail_diff/activity_event_record_resolver.rb +45 -32
  18. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +26 -33
  19. data/lib/paper_trail_diff/activity_history.rb +28 -34
  20. data/lib/paper_trail_diff/activity_relationship.rb +3 -26
  21. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +14 -8
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +2 -3
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +92 -25
  24. data/lib/paper_trail_diff/activity_timeline_builder.rb +128 -77
  25. data/lib/paper_trail_diff/activity_transaction_applier.rb +49 -0
  26. data/lib/paper_trail_diff/activity_tree_filter.rb +70 -57
  27. data/lib/paper_trail_diff/activity_tree_places.rb +76 -0
  28. data/lib/paper_trail_diff/activity_version_collector.rb +45 -32
  29. data/lib/paper_trail_diff/activity_view.rb +2 -0
  30. data/lib/paper_trail_diff/analysis.rb +6 -5
  31. data/lib/paper_trail_diff/analysis_batch.rb +21 -17
  32. data/lib/paper_trail_diff/association_activity_edge.rb +99 -85
  33. data/lib/paper_trail_diff/association_activity_selection.rb +46 -14
  34. data/lib/paper_trail_diff/association_discovery.rb +4 -4
  35. data/lib/paper_trail_diff/association_key.rb +10 -18
  36. data/lib/paper_trail_diff/association_traversal.rb +72 -92
  37. data/lib/paper_trail_diff/batch_boundary_resolver.rb +1 -7
  38. data/lib/paper_trail_diff/batch_preload.rb +2 -3
  39. data/lib/paper_trail_diff/batched_root_analyses.rb +60 -25
  40. data/lib/paper_trail_diff/batched_root_analyzer.rb +5 -5
  41. data/lib/paper_trail_diff/batched_root_versions.rb +7 -30
  42. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -14
  43. data/lib/paper_trail_diff/candidate_table.rb +160 -0
  44. data/lib/paper_trail_diff/change_attribution.rb +35 -28
  45. data/lib/paper_trail_diff/collection_identity_index.rb +68 -24
  46. data/lib/paper_trail_diff/collection_transition.rb +3 -3
  47. data/lib/paper_trail_diff/comparison_batch.rb +13 -6
  48. data/lib/paper_trail_diff/database_time.rb +85 -0
  49. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -23
  50. data/lib/paper_trail_diff/deleted_root_filter.rb +10 -6
  51. data/lib/paper_trail_diff/diagnostics.rb +26 -86
  52. data/lib/paper_trail_diff/endpoint.rb +37 -5
  53. data/lib/paper_trail_diff/engine.rb +1 -1
  54. data/lib/paper_trail_diff/errors.rb +0 -6
  55. data/lib/paper_trail_diff/exact_column_type.rb +96 -0
  56. data/lib/paper_trail_diff/historical_snapshot_store.rb +88 -83
  57. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  58. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -4
  59. data/lib/paper_trail_diff/live_graph_collector.rb +1 -3
  60. data/lib/paper_trail_diff/nested_comparator.rb +42 -10
  61. data/lib/paper_trail_diff/paper_trail_adapter.rb +55 -98
  62. data/lib/paper_trail_diff/prepared_activity_index.rb +235 -179
  63. data/lib/paper_trail_diff/prepared_child_candidates.rb +13 -3
  64. data/lib/paper_trail_diff/prepared_edge_loader.rb +11 -49
  65. data/lib/paper_trail_diff/prepared_history.rb +27 -177
  66. data/lib/paper_trail_diff/prepared_history_loader.rb +39 -57
  67. data/lib/paper_trail_diff/prepared_record_index.rb +221 -147
  68. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +47 -42
  69. data/lib/paper_trail_diff/prepared_state_association_reader.rb +85 -62
  70. data/lib/paper_trail_diff/recorded_changes.rb +34 -10
  71. data/lib/paper_trail_diff/recorded_owner.rb +67 -0
  72. data/lib/paper_trail_diff/root_version_selection.rb +6 -2
  73. data/lib/paper_trail_diff/scope_condition.rb +120 -80
  74. data/lib/paper_trail_diff/scope_ranking.rb +14 -32
  75. data/lib/paper_trail_diff/scoped_analysis.rb +11 -6
  76. data/lib/paper_trail_diff/scoped_analysis_builder.rb +17 -11
  77. data/lib/paper_trail_diff/scoped_root_selection.rb +91 -85
  78. data/lib/paper_trail_diff/selection_window.rb +31 -0
  79. data/lib/paper_trail_diff/snapshot.rb +60 -58
  80. data/lib/paper_trail_diff/snapshot_members.rb +115 -0
  81. data/lib/paper_trail_diff/snapshot_normalizer.rb +0 -11
  82. data/lib/paper_trail_diff/step.rb +1 -5
  83. data/lib/paper_trail_diff/stored_form.rb +146 -0
  84. data/lib/paper_trail_diff/stored_json_values.rb +8 -5
  85. data/lib/paper_trail_diff/stored_time_precision.rb +67 -33
  86. data/lib/paper_trail_diff/stored_values.rb +35 -3
  87. data/lib/paper_trail_diff/support.rb +185 -35
  88. data/lib/paper_trail_diff/time_of_day.rb +13 -2
  89. data/lib/paper_trail_diff/time_range.rb +85 -11
  90. data/lib/paper_trail_diff/time_version_range.rb +5 -1
  91. data/lib/paper_trail_diff/timeline_builder.rb +5 -11
  92. data/lib/paper_trail_diff/timeline_range.rb +56 -19
  93. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +31 -7
  94. data/lib/paper_trail_diff/total_order.rb +19 -5
  95. data/lib/paper_trail_diff/transaction_anchors.rb +138 -0
  96. data/lib/paper_trail_diff/transaction_cut.rb +67 -327
  97. data/lib/paper_trail_diff/transaction_ends.rb +194 -0
  98. data/lib/paper_trail_diff/traversal_preparer.rb +12 -24
  99. data/lib/paper_trail_diff/{approximate_paths.rb → unreadable_paths.rb} +8 -9
  100. data/lib/paper_trail_diff/value_objects.rb +8 -6
  101. data/lib/paper_trail_diff/version.rb +1 -1
  102. data/lib/paper_trail_diff/version_association_candidate_scope.rb +28 -4
  103. data/lib/paper_trail_diff/version_boundary.rb +0 -29
  104. data/lib/paper_trail_diff/version_query.rb +49 -1
  105. data/lib/paper_trail_diff/version_scope_filter.rb +74 -5
  106. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +4 -31
  107. data/lib/paper_trail_diff/version_table.rb +8 -1
  108. data/lib/paper_trail_diff.rb +56 -110
  109. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +24 -2
  110. data/sig/generated/paper_trail_diff/activity_boundary.rbs +6 -0
  111. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +46 -5
  112. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +7 -4
  113. data/sig/generated/paper_trail_diff/activity_collection_record_updater.rbs +11 -2
  114. data/sig/generated/paper_trail_diff/activity_collection_route_updater.rbs +8 -6
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +27 -18
  116. data/sig/generated/paper_trail_diff/activity_event_record_normalizer.rbs +7 -11
  117. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +26 -8
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +10 -2
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +23 -26
  120. data/sig/generated/paper_trail_diff/activity_relationship.rbs +0 -6
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +5 -0
  122. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +53 -10
  123. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +64 -38
  124. data/sig/generated/paper_trail_diff/activity_transaction_applier.rbs +28 -0
  125. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +46 -38
  126. data/sig/generated/paper_trail_diff/activity_tree_places.rbs +45 -0
  127. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +21 -11
  128. data/sig/generated/paper_trail_diff/analysis.rbs +6 -5
  129. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -6
  130. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +58 -45
  131. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +20 -3
  132. data/sig/generated/paper_trail_diff/association_discovery.rbs +2 -2
  133. data/sig/generated/paper_trail_diff/association_key.rbs +2 -11
  134. data/sig/generated/paper_trail_diff/association_traversal.rbs +43 -44
  135. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +0 -2
  136. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +40 -17
  137. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +2 -2
  138. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +2 -11
  139. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +12 -8
  140. data/sig/generated/paper_trail_diff/candidate_table.rbs +97 -0
  141. data/sig/generated/paper_trail_diff/change_attribution.rbs +21 -19
  142. data/sig/generated/paper_trail_diff/collection_identity_index.rbs +33 -13
  143. data/sig/generated/paper_trail_diff/collection_transition.rbs +2 -2
  144. data/sig/generated/paper_trail_diff/comparison_batch.rbs +5 -0
  145. data/sig/generated/paper_trail_diff/database_time.rbs +48 -0
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +13 -15
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +4 -0
  148. data/sig/generated/paper_trail_diff/diagnostics.rbs +13 -31
  149. data/sig/generated/paper_trail_diff/endpoint.rbs +14 -1
  150. data/sig/generated/paper_trail_diff/errors.rbs +0 -8
  151. data/sig/generated/paper_trail_diff/exact_column_type.rbs +51 -0
  152. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +51 -31
  153. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -5
  154. data/sig/generated/paper_trail_diff/nested_comparator.rbs +21 -0
  155. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +18 -29
  156. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +149 -94
  157. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +10 -2
  158. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +4 -21
  159. data/sig/generated/paper_trail_diff/prepared_history.rbs +22 -79
  160. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +24 -32
  161. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +137 -63
  162. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +22 -13
  163. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +41 -28
  164. data/sig/generated/paper_trail_diff/recorded_changes.rbs +19 -3
  165. data/sig/generated/paper_trail_diff/recorded_owner.rbs +39 -0
  166. data/sig/generated/paper_trail_diff/root_version_selection.rbs +4 -1
  167. data/sig/generated/paper_trail_diff/scope_condition.rbs +65 -52
  168. data/sig/generated/paper_trail_diff/scope_ranking.rbs +10 -23
  169. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +11 -6
  170. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +7 -2
  171. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +49 -43
  172. data/sig/generated/paper_trail_diff/selection_window.rbs +19 -0
  173. data/sig/generated/paper_trail_diff/snapshot.rbs +37 -38
  174. data/sig/generated/paper_trail_diff/snapshot_members.rbs +58 -0
  175. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +0 -4
  176. data/sig/generated/paper_trail_diff/stored_form.rbs +63 -0
  177. data/sig/generated/paper_trail_diff/stored_json_values.rbs +0 -2
  178. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +33 -20
  179. data/sig/generated/paper_trail_diff/stored_values.rbs +18 -2
  180. data/sig/generated/paper_trail_diff/support.rbs +96 -16
  181. data/sig/generated/paper_trail_diff/time_of_day.rbs +4 -0
  182. data/sig/generated/paper_trail_diff/time_range.rbs +49 -4
  183. data/sig/generated/paper_trail_diff/time_version_range.rbs +3 -0
  184. data/sig/generated/paper_trail_diff/timeline_builder.rbs +3 -6
  185. data/sig/generated/paper_trail_diff/timeline_range.rbs +29 -8
  186. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -4
  187. data/sig/generated/paper_trail_diff/total_order.rbs +9 -3
  188. data/sig/generated/paper_trail_diff/transaction_anchors.rbs +80 -0
  189. data/sig/generated/paper_trail_diff/transaction_cut.rbs +43 -176
  190. data/sig/generated/paper_trail_diff/transaction_ends.rbs +124 -0
  191. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +6 -11
  192. data/sig/generated/paper_trail_diff/{approximate_paths.rbs → unreadable_paths.rbs} +6 -7
  193. data/sig/generated/paper_trail_diff/value_objects.rbs +4 -2
  194. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +16 -2
  195. data/sig/generated/paper_trail_diff/version_boundary.rbs +0 -14
  196. data/sig/generated/paper_trail_diff/version_query.rbs +26 -0
  197. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +28 -2
  198. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +4 -15
  199. data/sig/generated/paper_trail_diff/version_table.rbs +4 -0
  200. data/sig/generated/paper_trail_diff.rbs +22 -23
  201. metadata +28 -20
  202. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +0 -123
  203. data/lib/paper_trail_diff/fallback_paths.rb +0 -35
  204. data/lib/paper_trail_diff/habtm_transaction_owners.rb +0 -70
  205. data/lib/paper_trail_diff/historical_association_reifier.rb +0 -161
  206. data/lib/paper_trail_diff/historical_filter.rb +0 -210
  207. data/lib/paper_trail_diff/own_window.rb +0 -35
  208. data/lib/paper_trail_diff/prepared_association_reifier.rb +0 -51
  209. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +0 -74
  210. data/sig/generated/paper_trail_diff/fallback_paths.rbs +0 -22
  211. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +0 -41
  212. data/sig/generated/paper_trail_diff/historical_association_reifier.rbs +0 -58
  213. data/sig/generated/paper_trail_diff/historical_filter.rbs +0 -96
  214. data/sig/generated/paper_trail_diff/own_window.rbs +0 -22
  215. data/sig/generated/paper_trail_diff/prepared_association_reifier.rbs +0 -27
@@ -7,11 +7,16 @@ module PaperTrailDiff
7
7
  attr_reader :version #: untyped
8
8
  attr_reader :branches #: Array[String]?
9
9
 
10
- #: (version: untyped, branches: Array[String]?, ?join: bool) -> void
11
- def initialize(version:, branches:, join: false)
10
+ # The branches under which the version is of a through's join row, which
11
+ # links the root to a target without being one. A record can be a join
12
+ # row under one branch and a member of another.
13
+ attr_reader :joins #: Array[String]
14
+
15
+ #: (version: untyped, branches: Array[String]?, ?joins: Array[String]) -> void
16
+ def initialize(version:, branches:, joins: [])
12
17
  @version = version
13
- @branches = branches ? branches.uniq.sort.freeze : nil
14
- @join = join
18
+ @branches = (branches.uniq.sort.freeze if branches)
19
+ @joins = joins.uniq.sort.freeze
15
20
  freeze
16
21
  end
17
22
 
@@ -19,15 +24,6 @@ module PaperTrailDiff
19
24
  def root?
20
25
  branches.nil?
21
26
  end
22
-
23
- # Whether the version is of a through's join row, which links the root to
24
- # a target without being one.
25
- #: () -> bool
26
- def join?
27
- @join
28
- end
29
-
30
- # @rbs @join: bool
31
27
  end
32
28
 
33
29
  # Accumulates each version once while retaining every selected root branch.
@@ -41,10 +37,11 @@ module PaperTrailDiff
41
37
  versions.each do |version|
42
38
  key = Support.row_key(version)
43
39
  existing = @events[key]
40
+ joins = existing ? existing.fetch(:joins) : [] #: Array[String]
44
41
  @events[key] = {
45
42
  version: version,
46
43
  branches: merged_branches(existing, branch),
47
- join: join || existing&.fetch(:join) || false
44
+ joins: join && branch ? joins | [branch] : joins
48
45
  }
49
46
  end
50
47
  end
@@ -55,7 +52,7 @@ module PaperTrailDiff
55
52
  ActivityEvent.new(
56
53
  version: event.fetch(:version),
57
54
  branches: event.fetch(:branches),
58
- join: event.fetch(:join)
55
+ joins: event.fetch(:joins)
59
56
  )
60
57
  end
61
58
  end
@@ -91,6 +88,30 @@ module PaperTrailDiff
91
88
  events.reject { |event| !event.root? && transaction_key(event.version) == key }.freeze
92
89
  end
93
90
 
91
+ # Where the root's destruction takes effect, its tree is gone, so what a
92
+ # transaction that ended later saved there is no change of the root's,
93
+ # until the root is created again. The transaction that creates it again
94
+ # is the root's, from its first event, as for a root created afresh.
95
+ #: (Array[ActivityEvent]) -> Array[ActivityEvent]
96
+ def self.until_destroyed(events)
97
+ gone = false
98
+ restoring = restoring_transactions(events)
99
+ events.reject do |event|
100
+ gone = event.version.event == 'destroy' if event.root?
101
+ gone && !event.root? && !restoring.include?(transaction_key(event.version))
102
+ end.freeze
103
+ end
104
+
105
+ # The transactions of the root's versions that leave it in place.
106
+ #: (Array[ActivityEvent]) -> Array[Array[untyped]?]
107
+ def self.restoring_transactions(events)
108
+ events.filter_map do |event|
109
+ next unless event.root?
110
+
111
+ transaction_key(event.version) unless event.version.event == 'destroy'
112
+ end
113
+ end
114
+
94
115
  # A version without a transaction shares one with nothing.
95
116
  #: (untyped) -> Array[untyped]?
96
117
  def self.transaction_key(version)
@@ -98,47 +119,45 @@ module PaperTrailDiff
98
119
  [version.class.name, transaction_id] if transaction_id
99
120
  end
100
121
 
101
- # An `opening` transaction began before the history's start, so its
102
- # versions there are not events, yet the state after it has their changes
103
- # (see PreparedHistoryLoader#reload). The snapshot after
104
- # it is read whole rather than refreshed from its events alone.
105
- #: (Array[ActivityEvent], ?opening: Array[Array[untyped]]) -> void
106
- def initialize(events, opening: [])
107
- groups = grouped_events(events)
108
- @branches = build_groups(groups)
109
- @group_sizes = groups.transform_values(&:length)
110
- @opening = opening
122
+ #: (Array[ActivityEvent]) -> void
123
+ def initialize(events)
124
+ @groups = grouped_events(events)
125
+ @branches = build_groups(@groups)
126
+ @group_sizes = @groups.transform_values(&:length)
127
+ end
128
+
129
+ # The events of the event's transaction, in the order they are replayed.
130
+ # The event is in a transaction with others.
131
+ #: (ActivityEvent) -> Array[ActivityEvent]
132
+ def events_for(event)
133
+ @groups.fetch(transaction_key(event))
111
134
  end
112
135
 
113
136
  # An event outside a transaction, or in one it was not given, keeps its
114
137
  # own.
115
138
  #: (ActivityEvent) -> Array[String]?
116
139
  def branches_for(event)
117
- key = transaction_key(event)
118
- return if @opening.include?(key)
119
-
120
- @branches.fetch(key) { event.branches }
140
+ @branches.fetch(transaction_key(event)) { event.branches }
121
141
  end
122
142
 
123
143
  #: (ActivityEvent) -> bool
124
144
  def isolated?(event)
125
145
  key = transaction_key(event)
126
- !key || (@group_sizes[key] == 1 && !@opening.include?(key))
146
+ !key || @group_sizes[key] == 1
127
147
  end
128
148
 
129
- # Whether two events were saved in one transaction that began inside the
130
- # history.
149
+ # Whether two events were saved in one transaction.
131
150
  #: (ActivityEvent, ActivityEvent) -> bool
132
151
  def shared?(left, right)
133
152
  key = transaction_key(left)
134
- !key.nil? && key == transaction_key(right) && !@opening.include?(key)
153
+ !key.nil? && key == transaction_key(right)
135
154
  end
136
155
 
137
156
  private
138
157
 
158
+ # @rbs @groups: Hash[Array[untyped]?, Array[ActivityEvent]]
139
159
  # @rbs @branches: Hash[Array[untyped]?, Array[String]?]
140
160
  # @rbs @group_sizes: Hash[Array[untyped]?, Integer]
141
- # @rbs @opening: Array[untyped]
142
161
 
143
162
  #: (Hash[Array[untyped]?, Array[ActivityEvent]]) -> Hash[Array[untyped]?, Array[String]?]
144
163
  def build_groups(groups)
@@ -2,45 +2,31 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Normalizes one event record with the historical reader for its boundary.
5
+ # Normalizes the state an event left, with its selected associations as
6
+ # the event's boundary reads them.
6
7
  class ActivityEventRecordNormalizer
7
- #: (?association_reader: untyped) -> void
8
- def initialize(association_reader: nil)
9
- @association_reader = association_reader || method(:historical_reader)
8
+ #: (member_snapshot: untyped) -> void
9
+ def initialize(member_snapshot:)
10
+ @member_snapshot = member_snapshot
10
11
  end
11
12
 
12
- #: (untyped, reflection: untyped, subtree: AssociationTree, path: String, normalizer: SnapshotNormalizer, root_endpoint: untyped, context_endpoint: untyped) -> RecordSnapshot?
13
+ #: (PreparedRecordState, reflection: untyped, subtree: AssociationTree, path: String, normalizer: SnapshotNormalizer, context_endpoint: untyped) -> RecordSnapshot
13
14
  def call( # rubocop:disable Metrics/ParameterLists
14
- record,
15
+ state,
15
16
  reflection:,
16
17
  subtree:,
17
18
  path:,
18
19
  normalizer:,
19
- root_endpoint:,
20
20
  context_endpoint:
21
21
  )
22
- if record.is_a?(PreparedRecordState)
23
- return normalizer.from_state(record, tree: subtree, path: path, incoming: reflection)
22
+ if subtree.empty?
23
+ return normalizer.from_state(state, tree: subtree, path: path, incoming: reflection)
24
24
  end
25
25
 
26
- boundary = Endpoint.version?(root_endpoint) ? root_endpoint : context_endpoint
27
- reifier = @association_reader.call(context_endpoint, habtm_version: boundary)
28
- normalizer.call_child(
29
- record,
30
- tree: subtree,
31
- path: path,
32
- incoming: reflection,
33
- reifier: reifier
34
- )
26
+ @member_snapshot.call(state, context_endpoint, tree: subtree, path: path,
27
+ incoming: reflection, normalizer: normalizer)
35
28
  end
36
29
 
37
- private
38
-
39
- # @rbs @association_reader: untyped
40
-
41
- #: (untyped, habtm_version: untyped) -> HistoricalAssociationReifier
42
- def historical_reader(context_endpoint, habtm_version:)
43
- HistoricalAssociationReifier.new(context_endpoint, habtm_version: habtm_version)
44
- end
30
+ # @rbs @member_snapshot: untyped
45
31
  end
46
32
  end
@@ -11,22 +11,14 @@ module PaperTrailDiff
11
11
  end
12
12
 
13
13
  # The record as the version left it: the state recorded next, which holds
14
- # any change saved after the version without one of its own. Prepared
15
- # history answers without a query; without it, the next version or the
16
- # live row does.
17
- #: (untyped, ?direct: bool) -> untyped
18
- def record_after(version, direct: false)
14
+ # any change saved after the version without one of its own. Every event
15
+ # comes from versions the prepared history loaded, so it answers without
16
+ # a query.
17
+ #: (untyped) -> PreparedRecordState?
18
+ def record_after(version)
19
19
  return if version.event.to_s == 'destroy'
20
20
 
21
- if direct
22
- handled, state = @prepared_record_after&.call(version, direct: true)
23
- return state if handled
24
- end
25
-
26
- handled, prepared = @prepared_record_after&.call(version)
27
- return prepared if handled
28
-
29
- recorded_after(version)
21
+ @prepared_record_after.call(version).last
30
22
  end
31
23
 
32
24
  #: (untyped) -> ActivitySnapshotDelta?
@@ -47,9 +39,7 @@ module PaperTrailDiff
47
39
  #: (untyped, untyped) -> untyped
48
40
  def deserialized_changeset(version, model_class)
49
41
  return unless model_class
50
- unless version.class.column_names.include?('object_changes')
51
- return prepared_changeset(version)
52
- end
42
+ return prepared_changeset(version) unless version.respond_to?(:object_changes)
53
43
 
54
44
  paper_trail = Object.const_get(:PaperTrail) #: untyped
55
45
  adapter = paper_trail.config.object_changes_adapter
@@ -64,17 +54,6 @@ module PaperTrailDiff
64
54
  # @rbs @record_transition: untyped
65
55
  # @rbs @prepared_record_after: untyped
66
56
 
67
- #: (untyped) -> untyped
68
- def recorded_after(version)
69
- successor = version.next
70
- record = successor && Support.reify(successor, dup: true)
71
- return record if record
72
-
73
- model_class = Endpoint.model_class(version)
74
- criteria = { model_class.primary_key => version.item_id } #: Hash[untyped, untyped]
75
- model_class.unscoped.find_by(criteria)
76
- end
77
-
78
57
  #: (untyped) -> untyped
79
58
  def prepared_changeset(version)
80
59
  transition = @record_transition&.call(version)
@@ -86,14 +65,48 @@ module PaperTrailDiff
86
65
  end.to_h
87
66
  end
88
67
 
68
+ # PaperTrail's own changeset holds the changes in a
69
+ # HashWithIndifferentAccess, which turns every hash inside a value into
70
+ # one with string keys, so a `serialize`d hash edited from symbol keys to
71
+ # strings would read as no change. Keys are strings already here.
89
72
  #: (untyped, untyped, untyped) -> untyped
90
73
  def standard_changeset(paper_trail, version, model_class)
91
- raw_changes = Support.decodable(version.send(:object_changes_deserialized))
92
- active_support = Object.const_get(:ActiveSupport) #: untyped
93
- changes = active_support.const_get(:HashWithIndifferentAccess).new(raw_changes)
74
+ changes = Support.decodable(stored_changes(version), model_class)
94
75
  serializers = paper_trail.const_get(:AttributeSerializers)
95
76
  serializers.const_get(:ObjectChangesAttribute).new(model_class).deserialize(changes)
96
- changes
77
+ json_column?(version) ? cast(model_class, changes) : changes
78
+ end
79
+
80
+ # PaperTrail's version model decodes its own column; a version that is
81
+ # not one holds the serializer's text.
82
+ #: (untyped) -> untyped
83
+ def stored_changes(version)
84
+ return version.send(:object_changes_deserialized) if version.respond_to?(
85
+ :object_changes_deserialized, true
86
+ )
87
+
88
+ Object.const_get(:PaperTrail).serializer.load(version.object_changes)
89
+ end
90
+
91
+ #: (untyped) -> bool
92
+ def json_column?(version)
93
+ StoredTimePrecision.json_column?(version.class, 'object_changes')
94
+ end
95
+
96
+ # PaperTrail writes a `json` or `jsonb` column without its attribute
97
+ # serializer and reads it back the same way, so a decimal, a date and a
98
+ # time are still the strings JSON gave. Each is cast as assigning it to
99
+ # the record would, which is how a version's stored state is read. A
100
+ # `serialize`d value stays as JSON wrote it, which is the form every
101
+ # account of it is read in (StoredJsonValues).
102
+ #: (untyped, untyped) -> untyped
103
+ def cast(model_class, changes)
104
+ changes.to_h do |name, values|
105
+ type = model_class.type_for_attribute(name)
106
+ serialized = type.is_a?(Support.constant(Support::SERIALIZED_TYPE))
107
+ cast = serialized || !values.instance_of?(Array) ? values : values.map { |v| type.cast(v) }
108
+ [name, cast]
109
+ end
97
110
  end
98
111
  end
99
112
  end
@@ -4,23 +4,22 @@
4
4
  module PaperTrailDiff
5
5
  # Dispatches safe descendant events to focused immutable snapshot appliers.
6
6
  class ActivityEventSnapshotRefresher
7
- #: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, ?association_reader: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
8
- def initialize(traversal:, pool:, components:, association_reader: nil, record_transition: nil, prepared_record_after: nil) # rubocop:disable Layout/LineLength, Metrics/ParameterLists
7
+ #: (traversal: AssociationTraversal, pool: SnapshotPool, components: untyped, member_snapshot: untyped, ?record_transition: untyped, ?prepared_record_after: untyped) -> void
8
+ def initialize(traversal:, pool:, components:, member_snapshot:, record_transition: nil, prepared_record_after: nil) # rubocop:disable Layout/LineLength, Metrics/ParameterLists
9
9
  @components = components
10
10
  @record_resolver = ActivityEventRecordResolver.new(
11
11
  record_transition: record_transition, prepared_record_after: prepared_record_after
12
12
  )
13
13
  @route_finder = ActivityEventRouteFinder.new(traversal)
14
+ @places = ActivityTreePlaces.new(traversal)
14
15
  @relationship = ActivityRelationship.new
15
- configure_appliers(pool, association_reader)
16
+ configure_appliers(pool, member_snapshot)
16
17
  end
17
18
 
18
19
  #: (SnapshotPool, untyped) -> void
19
- def configure_appliers(pool, association_reader)
20
+ def configure_appliers(pool, member_snapshot)
20
21
  route_updater = collection_updater(pool)
21
- record_normalizer = ActivityEventRecordNormalizer.new(
22
- association_reader: association_reader
23
- )
22
+ record_normalizer = ActivityEventRecordNormalizer.new(member_snapshot: member_snapshot)
24
23
  @collection_applier = collection_applier(record_normalizer, route_updater)
25
24
  @belongs_to_applier = belongs_to_applier(record_normalizer)
26
25
  end
@@ -49,47 +48,41 @@ module PaperTrailDiff
49
48
  )
50
49
  end
51
50
 
51
+ # Nothing is applied for a record with places of two kinds in the tree,
52
+ # since an event is applied at those of one kind only (see
53
+ # ActivityTreePlaces).
52
54
  #: (untyped, untyped, RecordSnapshot, Array[String], ActivityEvent?) -> [bool, RecordSnapshot?]
53
- def call( # rubocop:disable Metrics/MethodLength
54
- root_endpoint,
55
- context_endpoint,
56
- previous,
57
- branches,
58
- event
59
- )
55
+ def call(root_endpoint, context_endpoint, previous, branches, event)
60
56
  return [false, nil] unless event && branches.one?
61
57
 
58
+ root_class = RecordedClass.of_endpoint(root_endpoint)
59
+ return [false, nil] unless @places.one_kind?(root_class, event.version.item_type.to_s)
60
+
61
+ apply(root_class, [root_endpoint, context_endpoint], previous, branches, event)
62
+ end
63
+
64
+ private
65
+
66
+ #: (untyped, Array[untyped], RecordSnapshot, Array[String], ActivityEvent) -> [bool, RecordSnapshot?]
67
+ def apply(root_class, endpoints, previous, branches, event)
68
+ root_endpoint, context_endpoint = endpoints
62
69
  tree, normalizer = @components.call(branches)
63
- routes = @route_finder.collection_routes(
64
- RecordedClass.of_endpoint(root_endpoint), tree, event.version.item_type.to_s
65
- )
70
+ routes = @route_finder.collection_routes(root_class, tree, event.version.item_type.to_s)
66
71
  unless routes.empty?
67
72
  delta = @record_resolver.snapshot_delta(event.version)
68
73
  return [false, nil] unless collection_safe?(root_endpoint, tree, routes, event, delta)
69
74
 
70
75
  return @collection_applier.call(
71
- root_endpoint,
72
- context_endpoint,
73
- previous,
74
- normalizer,
75
- routes,
76
- event.version,
77
- delta
76
+ root_endpoint, context_endpoint, previous, normalizer, routes, event.version, delta
78
77
  )
79
78
  end
80
79
 
81
80
  @belongs_to_applier.call(
82
- root_endpoint,
83
- context_endpoint,
84
- previous,
85
- tree,
86
- normalizer,
87
- event.version
81
+ root_endpoint, context_endpoint, previous, tree, normalizer, event.version
88
82
  )
89
83
  end
90
84
 
91
- private
92
-
85
+ # @rbs @places: ActivityTreePlaces
93
86
  # @rbs @components: untyped
94
87
  # @rbs @record_resolver: ActivityEventRecordResolver
95
88
  # @rbs @route_finder: ActivityEventRouteFinder
@@ -112,7 +105,7 @@ module PaperTrailDiff
112
105
 
113
106
  #: (untyped) -> untyped
114
107
  def record_after(version)
115
- @record_resolver.record_after(version, direct: true)
108
+ @record_resolver.record_after(version)
116
109
  end
117
110
 
118
111
  #: (untyped, untyped) -> untyped
@@ -40,13 +40,16 @@ module PaperTrailDiff
40
40
  # the current record. Any other range ends at a root event, or at events
41
41
  # after a window whose steps are not reported, so nothing reads it.
42
42
  # `include_step` says whether an event's step is reported. `root` names
43
- # the root, whose steps then credit each change row to the version that
44
- # made it (see ChangeAttribution).
45
- #: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, include_step: untyped, ?current: untyped, ?closing: RecordSnapshot?, ?root: RecordReference?) -> void
43
+ # the root, whose steps credit each change row to the version that made
44
+ # it (see ChangeAttribution). `filtered` says a version filter chooses the
45
+ # reported steps, so that the history ends after the last change it keeps.
46
+ #: (Array[untyped], Array[ActivityEvent], untyped, view: ActivityView, include_step: untyped, root: RecordReference, ends: TransactionEnds, ?current: untyped, ?closing: RecordSnapshot?, ?filtered: bool) -> void
46
47
  def initialize( # rubocop:disable Metrics/ParameterLists
47
48
  root_versions, events, snapshotter,
48
- view:, include_step:, current: nil, closing: nil, root: nil
49
+ view:, include_step:, root:, ends:, current: nil, closing: nil, filtered: false
49
50
  )
51
+ @filtered = filtered
52
+ @ends = ends
50
53
  @root_versions = root_versions
51
54
  @events = events
52
55
  @snapshotter = snapshotter
@@ -96,13 +99,14 @@ module PaperTrailDiff
96
99
  # @rbs @previous_event: ActivityEvent?
97
100
  # @rbs @previous_attribution: ChangeAttribution?
98
101
  # @rbs @passed_reported: bool?
99
- # @rbs @root: RecordReference?
102
+ # @rbs @filtered: bool
103
+ # @rbs @root: RecordReference
104
+ # @rbs @ends: TransactionEnds
100
105
  # @rbs @transactions: Hash[Array[untyped], ChangeAttribution::Transaction]
101
- # @rbs @opening: Array[Array[untyped]]?
102
106
 
103
107
  #: () -> ActivityTreeFilter
104
108
  def filter
105
- ActivityTreeFilter.new(@events, reported: @include_step, closing: @closing)
109
+ ActivityTreeFilter.new(@events, closing: @closing)
106
110
  end
107
111
 
108
112
  #: () -> ActivitySnapshotSequence
@@ -111,19 +115,20 @@ module PaperTrailDiff
111
115
  @root_versions,
112
116
  @events,
113
117
  @snapshotter,
118
+ ends: @ends,
114
119
  current: @current
115
120
  )
116
121
  end
117
122
 
118
123
  # A left-out event bounds nothing. A reported step it would have opened
119
- # still moves the reported range's end past it, to the next boundary.
124
+ # still moves the reported range's end past it, to the next boundary,
125
+ # unless a version filter chooses the steps: the event changed nothing
126
+ # the root shows, so the last change the filter keeps is still the end.
120
127
  #
121
128
  # The history starts at the first kept event whose step is reported. The
122
- # events left out before it change nothing the root shows, unless they are
123
- # of a transaction that crossed the window's start and has no event kept
124
- # here: the snapshot at them is the state before that transaction, whose
125
- # changes the window before this one reports (see ActivityTreeFilter). And
126
- # a version filter starts it at the first change it keeps.
129
+ # events left out before it are of records outside the root's tree, and
130
+ # change nothing the root shows (see ActivityTreeFilter). And a version
131
+ # filter starts it at the first change it keeps.
127
132
  #: (ActivityEvent, RecordSnapshot?, bool) -> void
128
133
  def consume(event, snapshot, kept)
129
134
  return pass(event) unless kept
@@ -145,39 +150,28 @@ module PaperTrailDiff
145
150
  # Inside a transaction a record's change can surface at a later event
146
151
  # than its own, so the rows of a step its boundary opens are read with
147
152
  # the boundaries its transaction kept before it (see ChangeAttribution).
148
- #: (ActivityEvent, ActivityBoundary) -> ChangeAttribution?
153
+ #: (ActivityEvent, ActivityBoundary) -> ChangeAttribution
149
154
  def attribution(event, boundary)
150
- root = @root
151
- return unless root
152
-
153
- transaction, complete = transaction_of(event)
154
- attribution = ChangeAttribution.new(root: root, sources: [boundary], transaction: transaction,
155
- complete: complete)
155
+ transaction = transaction_of(event)
156
+ attribution = ChangeAttribution.new(root: @root, sources: [boundary],
157
+ transaction: transaction)
156
158
  transaction.add(boundary)
157
159
  attribution
158
160
  end
159
161
 
160
- # The boundaries kept so far of the event's transaction, and whether the
161
- # history holds all of it. A version saved outside a transaction is a
162
- # transaction of its own.
163
- #: (ActivityEvent) -> [ChangeAttribution::Transaction, bool]
162
+ # The boundaries kept so far of the event's transaction. A version saved
163
+ # outside a transaction is a transaction of its own.
164
+ #: (ActivityEvent) -> ChangeAttribution::Transaction
164
165
  def transaction_of(event)
165
166
  key = ActivityTransactionGroups.transaction_key(event.version)
166
- return [ChangeAttribution::Transaction.new, true] unless key
167
-
168
- [@transactions[key] ||= ChangeAttribution::Transaction.new, !opening.include?(key)]
169
- end
167
+ return ChangeAttribution::Transaction.new unless key
170
168
 
171
- # The transactions that began before the history did (see
172
- # PreparedHistoryLoader#reload).
173
- #: () -> Array[Array[untyped]]
174
- def opening
175
- @opening ||= @snapshotter.opening_transactions
169
+ @transactions[key] ||= ChangeAttribution::Transaction.new
176
170
  end
177
171
 
178
172
  #: (ActivityEvent) -> void
179
173
  def pass(event)
180
- @passed_reported = true if reported?(event)
174
+ @passed_reported = true if !@filtered && reported?(event)
181
175
  end
182
176
 
183
177
  #: (ActivityEvent, RecordSnapshot?) -> void
@@ -6,24 +6,17 @@ module PaperTrailDiff
6
6
  class ActivityRelationship
7
7
  #: (untyped, untyped, RecordSnapshot, ?state: Symbol) -> bool
8
8
  def member_of_owner?(record, reflection, owner, state: :after)
9
- actual = relationship_owner_values(record, reflection, state: state)
10
- expected_ids = Array(owner.id)
11
- # @type var expected_ids: Array[untyped]
12
- expected = expected_ids.map { |id| id.to_s } # rubocop:disable Style/SymbolProc
13
- return false unless actual == expected
9
+ return false unless owner_id(record, reflection, state: state).to_s == owner.id.to_s
14
10
  return false unless sti_member?(record, reflection, state)
15
11
  return true unless reflection.options[:as]
16
12
 
17
13
  type = event_attribute(record, reflection.type, state: state).to_s
18
- owner_types(reflection, owner).include?(type)
14
+ type == AssociationTraversal.owner_type(reflection)
19
15
  end
20
16
 
21
17
  #: (untyped, untyped, state: Symbol) -> untyped
22
18
  def owner_id(record, reflection, state:)
23
- values = Array(reflection.foreign_key).map do |foreign_key|
24
- event_attribute(record, foreign_key, state: state)
25
- end
26
- values.one? ? values.first : values
19
+ event_attribute(record, reflection.foreign_key, state: state)
27
20
  end
28
21
 
29
22
  private
@@ -39,13 +32,6 @@ module PaperTrailDiff
39
32
  AssociationTraversal.sti_member?(model_class, attributes)
40
33
  end
41
34
 
42
- #: (untyped, untyped, state: Symbol) -> Array[String]
43
- def relationship_owner_values(record, reflection, state:)
44
- Array(reflection.foreign_key).map do |key|
45
- event_attribute(record, key, state: state).to_s
46
- end
47
- end
48
-
49
35
  #: (untyped, untyped, state: Symbol) -> untyped
50
36
  def event_attribute(record, name, state:)
51
37
  return record.attributes[name.to_s] if record.is_a?(PreparedRecordState)
@@ -56,14 +42,5 @@ module PaperTrailDiff
56
42
 
57
43
  record.public_send(name)
58
44
  end
59
-
60
- #: (untyped, RecordSnapshot) -> Array[String]
61
- def owner_types(reflection, owner)
62
- [
63
- owner.type.to_s,
64
- reflection.active_record.name.to_s,
65
- reflection.active_record.base_class.name.to_s
66
- ]
67
- end
68
45
  end
69
46
  end
@@ -26,6 +26,7 @@ module PaperTrailDiff
26
26
  @root_state = root_state
27
27
  @unsupported_branches = {} #: Hash[String, Array[String]]
28
28
  @relationship_reflections = {} #: Hash[String, Array[untyped]]
29
+ @places = ActivityTreePlaces.new(traversal)
29
30
  end
30
31
 
31
32
  # `previous` is the snapshot at the root's `event`, and the result the one
@@ -47,6 +48,12 @@ module PaperTrailDiff
47
48
 
48
49
  private
49
50
 
51
+ #: (untyped) -> bool
52
+ def root_only?(root_endpoint)
53
+ root_class = RecordedClass.of_endpoint(root_endpoint)
54
+ @places.one_kind?(root_class, root_class.base_class.name)
55
+ end
56
+
50
57
  # The snapshot at a root version starts from the state stored in that
51
58
  # version, and the next one from the state at its own root endpoint. Where
52
59
  # prepared history built both from those states, the two are compared
@@ -54,6 +61,10 @@ module PaperTrailDiff
54
61
  # recorded change and the record after it are read.
55
62
  #: (RecordSnapshot, untyped, untyped) -> [untyped, Array[String]]?
56
63
  def target(previous, version, root_endpoint)
64
+ # A root that a path leads back to is changed there too, which only
65
+ # reading the snapshot again shows.
66
+ return unless root_only?(root_endpoint)
67
+
57
68
  before = @root_state&.call(version)
58
69
  after = before && @root_state&.call(root_endpoint)
59
70
  return advance_target(previous, version) unless before && after
@@ -108,6 +119,7 @@ module PaperTrailDiff
108
119
  associations: associations)
109
120
  end
110
121
 
122
+ # @rbs @places: ActivityTreePlaces
111
123
  # @rbs @tree: AssociationTree
112
124
  # @rbs @traversal: AssociationTraversal
113
125
  # @rbs @normalizer: SnapshotNormalizer
@@ -165,7 +177,6 @@ module PaperTrailDiff
165
177
  def direct_versioned_reflection?(reflection)
166
178
  return true if reflection.polymorphic?
167
179
  return false if reflection.options[:through]
168
- return false if reflection.macro == :has_and_belongs_to_many
169
180
 
170
181
  paper_trail = Object.const_get(:PaperTrail) #: untyped
171
182
  paper_trail.request.enabled_for_model?(reflection.klass)
@@ -200,13 +211,8 @@ module PaperTrailDiff
200
211
 
201
212
  #: (untyped) -> Array[String]
202
213
  def relationship_columns(reflection)
203
- foreign_keys = Array(reflection.foreign_key)
204
- # @type var foreign_keys: Array[untyped]
205
- columns = foreign_keys.map do |name| # rubocop:disable Style/SymbolProc
206
- name.to_s
207
- end
208
- columns << reflection.foreign_type.to_s if reflection.polymorphic?
209
- columns
214
+ key = reflection.foreign_key.to_s
215
+ reflection.polymorphic? ? [key, reflection.foreign_type.to_s] : [key]
210
216
  end
211
217
  end
212
218
  end