paper_trail_diff 0.15.0 → 0.17.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 (206) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +724 -1
  3. data/README.md +43 -8
  4. data/docs/architecture.md +7 -5
  5. data/docs/performance.md +89 -32
  6. data/docs/reference.md +427 -96
  7. data/docs/testing.md +260 -32
  8. data/lib/paper_trail_diff/activity_belongs_to_event_applier.rb +2 -16
  9. data/lib/paper_trail_diff/activity_boundary.rb +55 -34
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +46 -57
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -11
  12. data/lib/paper_trail_diff/activity_collection_route_updater.rb +1 -1
  13. data/lib/paper_trail_diff/activity_event.rb +33 -21
  14. data/lib/paper_trail_diff/activity_event_record_resolver.rb +16 -116
  15. data/lib/paper_trail_diff/activity_event_route_finder.rb +49 -18
  16. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +13 -7
  17. data/lib/paper_trail_diff/activity_history.rb +90 -49
  18. data/lib/paper_trail_diff/activity_range.rb +9 -35
  19. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +104 -52
  20. data/lib/paper_trail_diff/activity_root_steps.rb +10 -13
  21. data/lib/paper_trail_diff/activity_scope_filter.rb +77 -0
  22. data/lib/paper_trail_diff/activity_snapshot_delta.rb +12 -15
  23. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +37 -15
  24. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +35 -43
  25. data/lib/paper_trail_diff/activity_timeline_builder.rb +200 -249
  26. data/lib/paper_trail_diff/activity_transaction_grouper.rb +3 -1
  27. data/lib/paper_trail_diff/activity_tree_filter.rb +54 -13
  28. data/lib/paper_trail_diff/activity_version_collector.rb +72 -138
  29. data/lib/paper_trail_diff/activity_view.rb +22 -11
  30. data/lib/paper_trail_diff/analysis.rb +39 -6
  31. data/lib/paper_trail_diff/analysis_batch.rb +16 -58
  32. data/lib/paper_trail_diff/approximate_paths.rb +4 -8
  33. data/lib/paper_trail_diff/association_activity_edge.rb +5 -24
  34. data/lib/paper_trail_diff/association_activity_selection.rb +10 -18
  35. data/lib/paper_trail_diff/association_discovery.rb +1 -6
  36. data/lib/paper_trail_diff/association_key.rb +9 -6
  37. data/lib/paper_trail_diff/association_traversal.rb +49 -6
  38. data/lib/paper_trail_diff/batch_boundary_resolver.rb +33 -42
  39. data/lib/paper_trail_diff/batch_preload.rb +2 -12
  40. data/lib/paper_trail_diff/batched_root_analyses.rb +72 -0
  41. data/lib/paper_trail_diff/batched_root_analyzer.rb +22 -14
  42. data/lib/paper_trail_diff/batched_root_versions.rb +25 -20
  43. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +41 -42
  44. data/lib/paper_trail_diff/change_attribution.rb +314 -0
  45. data/lib/paper_trail_diff/change_row.rb +30 -10
  46. data/lib/paper_trail_diff/comparison_batch.rb +3 -4
  47. data/lib/paper_trail_diff/configuration.rb +1 -1
  48. data/lib/paper_trail_diff/deleted_analysis_batch.rb +22 -33
  49. data/lib/paper_trail_diff/deleted_root_filter.rb +29 -10
  50. data/lib/paper_trail_diff/deprecation.rb +4 -43
  51. data/lib/paper_trail_diff/diagnostics.rb +8 -7
  52. data/lib/paper_trail_diff/direct_record_state_loader.rb +8 -1
  53. data/lib/paper_trail_diff/endpoint.rb +78 -44
  54. data/lib/paper_trail_diff/errors.rb +2 -9
  55. data/lib/paper_trail_diff/fallback_paths.rb +2 -5
  56. data/lib/paper_trail_diff/habtm_transaction_owners.rb +5 -3
  57. data/lib/paper_trail_diff/historical_association_reifier.rb +3 -1
  58. data/lib/paper_trail_diff/historical_filter.rb +40 -15
  59. data/lib/paper_trail_diff/historical_snapshot_store.rb +80 -38
  60. data/lib/paper_trail_diff/instrumentation.rb +0 -8
  61. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +11 -7
  62. data/lib/paper_trail_diff/live_endpoint_provider.rb +7 -23
  63. data/lib/paper_trail_diff/live_graph_collector.rb +3 -3
  64. data/lib/paper_trail_diff/nested_comparator.rb +46 -19
  65. data/lib/paper_trail_diff/net_change.rb +276 -0
  66. data/lib/paper_trail_diff/own_window.rb +35 -0
  67. data/lib/paper_trail_diff/paper_trail_adapter.rb +119 -87
  68. data/lib/paper_trail_diff/prepared_activity_index.rb +182 -50
  69. data/lib/paper_trail_diff/prepared_child_candidates.rb +58 -0
  70. data/lib/paper_trail_diff/prepared_edge_loader.rb +43 -107
  71. data/lib/paper_trail_diff/prepared_history.rb +31 -36
  72. data/lib/paper_trail_diff/prepared_history_loader.rb +47 -12
  73. data/lib/paper_trail_diff/prepared_record_index.rb +143 -49
  74. data/lib/paper_trail_diff/prepared_snapshot_builder.rb +16 -0
  75. data/lib/paper_trail_diff/prepared_state_association_reader.rb +17 -19
  76. data/lib/paper_trail_diff/read_snapshot.rb +99 -0
  77. data/lib/paper_trail_diff/recorded_changes.rb +10 -11
  78. data/lib/paper_trail_diff/recorded_changes_reader.rb +60 -0
  79. data/lib/paper_trail_diff/recorded_class.rb +14 -19
  80. data/lib/paper_trail_diff/recorded_columns.rb +33 -0
  81. data/lib/paper_trail_diff/root_version_plan.rb +20 -22
  82. data/lib/paper_trail_diff/root_version_selection.rb +39 -29
  83. data/lib/paper_trail_diff/scope_condition.rb +92 -32
  84. data/lib/paper_trail_diff/scope_ranking.rb +27 -34
  85. data/lib/paper_trail_diff/scoped_analysis.rb +27 -4
  86. data/lib/paper_trail_diff/scoped_analysis_builder.rb +18 -7
  87. data/lib/paper_trail_diff/scoped_root_selection.rb +65 -39
  88. data/lib/paper_trail_diff/snapshot_normalizer.rb +18 -3
  89. data/lib/paper_trail_diff/stored_json_values.rb +52 -0
  90. data/lib/paper_trail_diff/stored_time_precision.rb +30 -18
  91. data/lib/paper_trail_diff/stored_values.rb +20 -0
  92. data/lib/paper_trail_diff/support.rb +185 -35
  93. data/lib/paper_trail_diff/time_of_day.rb +39 -0
  94. data/lib/paper_trail_diff/time_range.rb +40 -22
  95. data/lib/paper_trail_diff/time_version_range.rb +5 -10
  96. data/lib/paper_trail_diff/timeline_builder.rb +9 -3
  97. data/lib/paper_trail_diff/timeline_range.rb +18 -12
  98. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +1 -1
  99. data/lib/paper_trail_diff/total_order.rb +55 -0
  100. data/lib/paper_trail_diff/transaction_cut.rb +235 -75
  101. data/lib/paper_trail_diff/traversal_preparer.rb +5 -8
  102. data/lib/paper_trail_diff/value_objects.rb +8 -4
  103. data/lib/paper_trail_diff/version.rb +1 -1
  104. data/lib/paper_trail_diff/version_association_candidate_scope.rb +1 -12
  105. data/lib/paper_trail_diff/version_boundary.rb +41 -23
  106. data/lib/paper_trail_diff/version_query.rb +25 -25
  107. data/lib/paper_trail_diff/version_range.rb +12 -16
  108. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +36 -1
  109. data/lib/paper_trail_diff/version_table.rb +12 -8
  110. data/lib/paper_trail_diff.rb +32 -44
  111. data/sig/generated/paper_trail_diff/activity_belongs_to_event_applier.rbs +0 -8
  112. data/sig/generated/paper_trail_diff/activity_boundary.rbs +39 -17
  113. data/sig/generated/paper_trail_diff/activity_child_candidate_loader.rbs +19 -22
  114. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -5
  115. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -9
  116. data/sig/generated/paper_trail_diff/activity_event_record_resolver.rbs +6 -34
  117. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +25 -4
  118. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -3
  119. data/sig/generated/paper_trail_diff/activity_history.rbs +54 -19
  120. data/sig/generated/paper_trail_diff/activity_range.rbs +6 -20
  121. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +55 -10
  122. data/sig/generated/paper_trail_diff/activity_root_steps.rbs +6 -6
  123. data/sig/generated/paper_trail_diff/activity_scope_filter.rbs +51 -0
  124. data/sig/generated/paper_trail_diff/activity_snapshot_delta.rbs +5 -3
  125. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +21 -3
  126. data/sig/generated/paper_trail_diff/activity_target_candidate_loader.rbs +19 -24
  127. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +125 -127
  128. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +41 -8
  129. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +42 -35
  130. data/sig/generated/paper_trail_diff/activity_view.rbs +16 -8
  131. data/sig/generated/paper_trail_diff/analysis.rbs +26 -5
  132. data/sig/generated/paper_trail_diff/analysis_batch.rbs +6 -24
  133. data/sig/generated/paper_trail_diff/association_activity_edge.rbs +0 -13
  134. data/sig/generated/paper_trail_diff/association_activity_selection.rbs +6 -9
  135. data/sig/generated/paper_trail_diff/association_discovery.rbs +0 -3
  136. data/sig/generated/paper_trail_diff/association_key.rbs +5 -0
  137. data/sig/generated/paper_trail_diff/association_traversal.rbs +26 -2
  138. data/sig/generated/paper_trail_diff/batch_boundary_resolver.rbs +17 -17
  139. data/sig/generated/paper_trail_diff/batch_preload.rbs +0 -4
  140. data/sig/generated/paper_trail_diff/batched_root_analyses.rbs +47 -0
  141. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -8
  142. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +10 -6
  143. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +16 -4
  144. data/sig/generated/paper_trail_diff/change_attribution.rbs +185 -0
  145. data/sig/generated/paper_trail_diff/change_row.rbs +22 -7
  146. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -9
  147. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +9 -3
  148. data/sig/generated/paper_trail_diff/deprecation.rbs +4 -24
  149. data/sig/generated/paper_trail_diff/direct_record_state_loader.rbs +4 -0
  150. data/sig/generated/paper_trail_diff/endpoint.rbs +40 -16
  151. data/sig/generated/paper_trail_diff/errors.rbs +2 -11
  152. data/sig/generated/paper_trail_diff/habtm_transaction_owners.rbs +2 -1
  153. data/sig/generated/paper_trail_diff/historical_filter.rbs +20 -9
  154. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +40 -10
  155. data/sig/generated/paper_trail_diff/instrumentation.rbs +0 -3
  156. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +3 -0
  157. data/sig/generated/paper_trail_diff/live_endpoint_provider.rbs +5 -8
  158. data/sig/generated/paper_trail_diff/live_graph_collector.rbs +2 -2
  159. data/sig/generated/paper_trail_diff/nested_comparator.rbs +20 -4
  160. data/sig/generated/paper_trail_diff/net_change.rbs +168 -0
  161. data/sig/generated/paper_trail_diff/own_window.rbs +22 -0
  162. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +19 -6
  163. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +113 -17
  164. data/sig/generated/paper_trail_diff/prepared_child_candidates.rbs +39 -0
  165. data/sig/generated/paper_trail_diff/prepared_edge_loader.rbs +18 -35
  166. data/sig/generated/paper_trail_diff/prepared_history.rbs +15 -13
  167. data/sig/generated/paper_trail_diff/prepared_history_loader.rbs +28 -3
  168. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +70 -15
  169. data/sig/generated/paper_trail_diff/prepared_snapshot_builder.rbs +12 -0
  170. data/sig/generated/paper_trail_diff/prepared_state_association_reader.rbs +6 -7
  171. data/sig/generated/paper_trail_diff/read_snapshot.rbs +62 -0
  172. data/sig/generated/paper_trail_diff/recorded_changes.rbs +4 -2
  173. data/sig/generated/paper_trail_diff/recorded_changes_reader.rbs +41 -0
  174. data/sig/generated/paper_trail_diff/recorded_class.rbs +7 -6
  175. data/sig/generated/paper_trail_diff/recorded_columns.rbs +21 -0
  176. data/sig/generated/paper_trail_diff/root_version_plan.rbs +8 -4
  177. data/sig/generated/paper_trail_diff/root_version_selection.rbs +27 -13
  178. data/sig/generated/paper_trail_diff/scope_condition.rbs +39 -9
  179. data/sig/generated/paper_trail_diff/scope_ranking.rbs +16 -16
  180. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +19 -0
  181. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +9 -2
  182. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +40 -12
  183. data/sig/generated/paper_trail_diff/snapshot_normalizer.rbs +7 -0
  184. data/sig/generated/paper_trail_diff/stored_json_values.rbs +35 -0
  185. data/sig/generated/paper_trail_diff/stored_time_precision.rbs +19 -5
  186. data/sig/generated/paper_trail_diff/stored_values.rbs +13 -0
  187. data/sig/generated/paper_trail_diff/support.rbs +120 -23
  188. data/sig/generated/paper_trail_diff/time_of_day.rbs +21 -0
  189. data/sig/generated/paper_trail_diff/time_range.rbs +15 -7
  190. data/sig/generated/paper_trail_diff/time_version_range.rbs +2 -5
  191. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  192. data/sig/generated/paper_trail_diff/timeline_range.rbs +12 -7
  193. data/sig/generated/paper_trail_diff/total_order.rbs +32 -0
  194. data/sig/generated/paper_trail_diff/transaction_cut.rbs +131 -40
  195. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +2 -2
  196. data/sig/generated/paper_trail_diff/value_objects.rbs +5 -1
  197. data/sig/generated/paper_trail_diff/version_association_candidate_scope.rbs +0 -7
  198. data/sig/generated/paper_trail_diff/version_boundary.rbs +17 -8
  199. data/sig/generated/paper_trail_diff/version_query.rbs +17 -10
  200. data/sig/generated/paper_trail_diff/version_range.rbs +6 -9
  201. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +16 -0
  202. data/sig/generated/paper_trail_diff/version_table.rbs +3 -0
  203. data/sig/generated/paper_trail_diff.rbs +16 -16
  204. metadata +31 -7
  205. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +0 -60
  206. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +0 -32
@@ -6,17 +6,15 @@ module PaperTrailDiff
6
6
  class PreparedHistory
7
7
  attr_reader :activity_index #: PreparedActivityIndex?
8
8
 
9
- DIRECT_RESOLVERS = {
10
- belongs_to: :resolve_belongs_to,
11
- has_one: :resolve_children,
12
- has_many: :resolve_children,
13
- has_and_belongs_to_many: :habtm_records
14
- }.freeze
15
- private_constant :DIRECT_RESOLVERS
16
-
17
- #: (PreparedRecordIndex, ?activity_index: PreparedActivityIndex?) -> void
18
- def initialize(records, activity_index: nil)
9
+ # The transactions that crossed the history's start, keyed as
10
+ # ActivityTransactionGroups keys a version's; see
11
+ # PreparedHistoryLoader#reload.
12
+ attr_reader :opening_transactions #: Array[Array[untyped]]
13
+
14
+ #: (PreparedRecordIndex, ?activity_index: PreparedActivityIndex?, ?opening_transactions: Array[Array[untyped]]) -> void
15
+ def initialize(records, activity_index: nil, opening_transactions: [])
19
16
  @records = records
17
+ @opening_transactions = opening_transactions
20
18
  @conditions = ScopeCondition::Cache.new
21
19
  @state_reader = PreparedStateAssociationReader.new(records, method(:edge), @conditions)
22
20
  @activity_index = activity_index
@@ -25,6 +23,9 @@ module PaperTrailDiff
25
23
  @habtm = {} #: Hash[Array[String], Hash[String, Array[untyped]]]
26
24
  end
27
25
 
26
+ #: () -> Array[untyped]
27
+ def versions = @records.versions
28
+
28
29
  # Returns every group the edge now holds.
29
30
  #: (untyped, untyped, Hash[String, Hash[Symbol, untyped]]) -> Hash[String, Hash[Symbol, untyped]]
30
31
  def merge_edge(owner_class, reflection, groups)
@@ -97,23 +98,17 @@ module PaperTrailDiff
97
98
 
98
99
  #: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
99
100
  def direct_records(record, reflection, boundary, habtm_boundary, ranked)
100
- resolver = DIRECT_RESOLVERS.fetch(reflection.macro)
101
- send(resolver, record, reflection, boundary, habtm_boundary, ranked)
102
- end
103
-
104
- #: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
105
- def resolve_belongs_to(record, reflection, boundary, _habtm_boundary, ranked)
106
- belongs_to_records(record, reflection, boundary, ranked)
107
- end
108
-
109
- #: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]
110
- def resolve_children(record, reflection, boundary, _habtm_boundary, ranked)
111
- child_records(record, reflection, boundary, ranked)
101
+ case reflection.macro
102
+ when :belongs_to then belongs_to_records(record, reflection, boundary, ranked)
103
+ when :has_one, :has_many then child_records(record, reflection, boundary, ranked)
104
+ when :has_and_belongs_to_many
105
+ habtm_records(record, reflection, boundary, habtm_boundary, ranked)
106
+ end
112
107
  end
113
108
 
114
109
  #: (untyped, untyped, untyped, bool) -> Array[untyped]?
115
110
  def belongs_to_records(record, reflection, boundary, ranked)
116
- foreign_key = scalar_foreign_key(reflection)
111
+ foreign_key = AssociationKey.scalar_foreign_key(reflection)
117
112
  return unless foreign_key
118
113
 
119
114
  id = record.public_send(foreign_key)
@@ -150,7 +145,9 @@ module PaperTrailDiff
150
145
  # saved, so a tag attached earlier in the checkpoint's own transaction is a
151
146
  # member there, unlike other associations, which a version reads as they
152
147
  # were before its transaction. A member created in that transaction has no
153
- # earlier state, so it is read as it was created.
148
+ # earlier state, so it is read as it was created, from its creation on.
149
+ # The checkpoint's membership also stands for earlier points, since the
150
+ # previous root version; the member did not exist at those yet.
154
151
  #: (untyped, untyped, untyped, untyped, bool) -> Array[untyped]?
155
152
  def habtm_records(record, reflection, boundary, habtm_boundary, ranked)
156
153
  transaction_id = transaction_id_for(habtm_boundary)
@@ -160,13 +157,17 @@ module PaperTrailDiff
160
157
  ids = @habtm.fetch(edge_key(record.class, reflection), empty)[transaction_id.to_s]
161
158
  return unless ids
162
159
 
163
- members = ids.filter_map do |id|
164
- @records.record_before(reflection.klass, id, boundary) ||
165
- @records.record_created_in(reflection.klass, id, habtm_boundary)
166
- end
160
+ created = VersionBoundary.transaction_id(boundary).to_s == transaction_id.to_s
161
+ members = ids.filter_map { |id| habtm_member(reflection.klass, id, boundary, created) }
167
162
  @conditions.select(reflection, members, ranked: ranked)
168
163
  end
169
164
 
165
+ #: (untyped, untyped, untyped, bool) -> untyped
166
+ def habtm_member(model_class, id, boundary, created)
167
+ @records.record_before(model_class, id, boundary) ||
168
+ (@records.record_created_in(model_class, id, boundary) if created)
169
+ end
170
+
170
171
  # A has_many through reads its parts unranked, as its query does. Its own
171
172
  # scope applies to each row, and a ranked read then keeps a record reached
172
173
  # twice as one member.
@@ -196,7 +197,7 @@ module PaperTrailDiff
196
197
 
197
198
  #: (untyped, untyped, untyped) -> bool
198
199
  def member_of?(child, reflection, owner)
199
- foreign_key = scalar_foreign_key(reflection)
200
+ foreign_key = AssociationKey.scalar_foreign_key(reflection)
200
201
  return false unless foreign_key
201
202
  return false unless child.public_send(foreign_key).to_s == owner.id.to_s
202
203
  return false unless AssociationTraversal.sti_member?(reflection.klass, child.attributes)
@@ -205,12 +206,6 @@ module PaperTrailDiff
205
206
  owner_types(reflection, owner).include?(child.public_send(reflection.type).to_s)
206
207
  end
207
208
 
208
- #: (untyped) -> String?
209
- def scalar_foreign_key(reflection)
210
- key = reflection.foreign_key
211
- key.to_s unless key.is_a?(Array)
212
- end
213
-
214
209
  #: (untyped, untyped) -> Array[String]
215
210
  def owner_types(reflection, owner)
216
211
  types = [owner.class.name, owner.class.base_class.name, reflection.active_record.name]
@@ -224,7 +219,7 @@ module PaperTrailDiff
224
219
 
225
220
  #: (Array[untyped]) -> Array[untyped]
226
221
  def unique_records(records)
227
- records.uniq { |record| [record.class.base_class.name, record.id.to_s] }
222
+ records.uniq { |record| Support.record_identity(record.class, record.id) }
228
223
  end
229
224
 
230
225
  #: (untyped, untyped) -> Array[String]
@@ -5,7 +5,10 @@ module PaperTrailDiff
5
5
  # Expands the explicit association tree into a request-scoped PreparedHistory.
6
6
  class PreparedHistoryLoader
7
7
  # Without `end_at`, the activity range closes on the last root version.
8
- #: (untyped, root_ids: Array[untyped], root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, start_at: untyped, end_at: untyped, live_records: Array[untyped]) -> void
8
+ # A `window` is a time range; a range of versions starts at the state its
9
+ # first version names. `opening` names the transactions that crossed the
10
+ # window's start when this history is read again from where they began.
11
+ #: (untyped, root_ids: Array[untyped], root_versions: Array[untyped], tree: AssociationTree, traversal: AssociationTraversal, start_at: untyped, end_at: untyped, live_records: Array[untyped], ?window: bool, ?opening: Array[Array[untyped]]) -> void
9
12
  def initialize( # rubocop:disable Metrics/ParameterLists
10
13
  record,
11
14
  root_ids:,
@@ -14,32 +17,42 @@ module PaperTrailDiff
14
17
  traversal:,
15
18
  start_at:,
16
19
  end_at:,
17
- live_records:
20
+ live_records:,
21
+ window: false,
22
+ opening: []
18
23
  )
24
+ @window = window
19
25
  @record = record
20
26
  @root_ids = root_ids
21
27
  @root_versions = root_versions
22
28
  @tree = tree
23
29
  @traversal = traversal
30
+ @end_at = end_at
31
+ @live_records = live_records
24
32
  start_at = VersionBoundary.transaction_start(root_versions, start_at)
25
33
  @records = PreparedRecordIndex.new(start_at, end_at: end_at, live_records: live_records)
26
- @activity = PreparedActivityIndex.new(
27
- @records, root_versions, start_at: start_at, end_at: end_at || root_versions.last.created_at
28
- )
29
- @history = PreparedHistory.new(@records, activity_index: @activity)
30
- @edges = PreparedEdgeLoader.new(@records, root_versions, start_at: start_at)
31
- @prepared = {} #: Hash[untyped, Array[String]]
34
+ @activity = PreparedActivityIndex.new(@records, root_versions, start_at: start_at)
35
+ @history = PreparedHistory.new(@records, activity_index: @activity,
36
+ opening_transactions: opening)
37
+ @edges = PreparedEdgeLoader.new(@records, root_versions, children: @activity.children)
38
+ @prepared = {} #: Hash[untyped, Set[String]]
32
39
  end
33
40
 
34
41
  #: () -> PreparedHistory
35
42
  def call
36
43
  @records.seed(@record.class, @root_ids, @root_versions)
37
44
  load_node(@record.class, @root_ids, @tree, path: '')
38
- @history
45
+ opening = @records.opening if @window
46
+ return @history unless opening
47
+
48
+ reload(*opening)
39
49
  end
40
50
 
41
51
  private
42
52
 
53
+ # @rbs @window: bool
54
+ # @rbs @end_at: untyped
55
+ # @rbs @live_records: Array[untyped]
43
56
  # @rbs @record: untyped
44
57
  # @rbs @root_ids: Array[untyped]
45
58
  # @rbs @root_versions: Array[untyped]
@@ -49,7 +62,29 @@ module PaperTrailDiff
49
62
  # @rbs @activity: PreparedActivityIndex
50
63
  # @rbs @history: PreparedHistory
51
64
  # @rbs @edges: PreparedEdgeLoader
52
- # @rbs @prepared: Hash[untyped, Array[String]]
65
+ # @rbs @prepared: Hash[untyped, Set[String]]
66
+
67
+ # A transaction that crosses a window's start and saved a version of the
68
+ # root moves the window's edge back to where it began (see
69
+ # TransactionCut); one that saved only associated records moves nothing.
70
+ # A boundary in such a transaction still reads each record as it stood
71
+ # before the transaction began (see PreparedRecordSeries#boundary_index),
72
+ # and a history read from the window's start holds neither the versions
73
+ # it saved before the start nor the records only those versions name, such
74
+ # as one it destroyed there. Without them the window would start after
75
+ # changes that the window before it left to this one, by ending its step
76
+ # at one of the transaction's events here (see ActivityTreeFilter), and
77
+ # neither would report them. So the history is read again from where the
78
+ # earliest such transaction began; the window's events still start at its
79
+ # start.
80
+ #: (Array[Array[untyped]], untyped) -> PreparedHistory
81
+ def reload(keys, earliest)
82
+ PreparedHistoryLoader.new(
83
+ @record, root_ids: @root_ids, root_versions: @root_versions, tree: @tree,
84
+ traversal: @traversal, start_at: earliest, end_at: @end_at,
85
+ live_records: @live_records, opening: keys
86
+ ).call
87
+ end
53
88
 
54
89
  #: (untyped, Array[untyped], AssociationTree, path: String) -> void
55
90
  def load_node(model_class, ids, tree, path:)
@@ -104,13 +139,13 @@ module PaperTrailDiff
104
139
  # the edge; a subclass that inherits it reads the same records.
105
140
  #: (Array[untyped], untyped) -> Array[untyped]
106
141
  def unprepared_ids(ids, reflection)
107
- prepared = @prepared.fetch(reflection, [])
142
+ prepared = @prepared.fetch(reflection) { Set.new }
108
143
  ids.reject { |id| prepared.include?(id.to_s) }
109
144
  end
110
145
 
111
146
  #: (Array[untyped], untyped) -> void
112
147
  def mark_prepared(ids, reflection)
113
- @prepared[reflection] = (@prepared.fetch(reflection, []) | ids.map(&:to_s))
148
+ (@prepared[reflection] ||= Set.new).merge(ids.map(&:to_s))
114
149
  end
115
150
 
116
151
  #: (untyped, untyped, Hash[String, Hash[Symbol, untyped]]) -> void
@@ -45,8 +45,7 @@ module PaperTrailDiff
45
45
  # change.
46
46
  #: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
47
47
  def stored_attributes(model_class, attributes)
48
- digits = StoredTimePrecision.digits(model_class)
49
- Support.immutable_copy(StoredTimePrecision.apply(attributes, digits))
48
+ Support.immutable_copy(StoredValues.apply(model_class, attributes))
50
49
  end
51
50
  end
52
51
 
@@ -65,7 +64,7 @@ module PaperTrailDiff
65
64
  attributes = version.object_deserialized
66
65
  return unless attributes.is_a?(Hash)
67
66
 
68
- attributes = stringify_keys(attributes)
67
+ attributes = Support.decodable(attributes)
69
68
  model_class = reification_class(version, attributes)
70
69
  return unless direct_attributes?(model_class, attributes)
71
70
 
@@ -80,11 +79,6 @@ module PaperTrailDiff
80
79
  # @rbs @serializers: Hash[untyped, untyped]
81
80
  # @rbs @attribute_names: Hash[untyped, Array[String]]
82
81
 
83
- #: (Hash[untyped, untyped]) -> Hash[String, untyped]
84
- def stringify_keys(attributes)
85
- attributes.to_h { |name, value| [name.to_s, value] }
86
- end
87
-
88
82
  #: (untyped, Hash[String, untyped]) -> untyped
89
83
  def reification_class(version, attributes)
90
84
  model_class = Endpoint.model_class(version)
@@ -116,14 +110,19 @@ module PaperTrailDiff
116
110
  class PreparedRecordSeries
117
111
  attr_reader :versions #: Array[untyped]
118
112
 
119
- #: (versions: Array[untyped], live: PreparedRecordState?, ?state_loader: PreparedVersionStateLoader) -> void
120
- def initialize(versions:, live:, state_loader: PreparedVersionStateLoader.new)
113
+ # The live fallback is a state, or a current record whose state is read
114
+ # the first time a read reaches past the last version. Most reads stop at
115
+ # a version, and reading a row's state casts every column it has.
116
+ #: (versions: Array[untyped], live: PreparedRecordState?, ?live_record: untyped, ?state_loader: PreparedVersionStateLoader) -> void
117
+ def initialize(versions:, live:, live_record: nil, state_loader: PreparedVersionStateLoader.new)
121
118
  @versions = Support.chronological_sort(versions).freeze
119
+ @times = @versions.map(&:created_at).freeze
122
120
  @version_positions = @versions.each_with_index.to_h do |version, index|
123
121
  [version.id.to_s, index]
124
122
  end.freeze
125
123
  @transaction_positions = build_transaction_positions
126
124
  @live = live
125
+ @live_record = live_record
127
126
  @state_loader = state_loader
128
127
  @states = {} #: Hash[untyped, PreparedRecordState?]
129
128
  end
@@ -135,11 +134,15 @@ module PaperTrailDiff
135
134
 
136
135
  # A record created in the boundary's own transaction has no state before
137
136
  # it, yet a HABTM checkpoint saved later in that transaction records it as
138
- # a member. Such a member is read as it was created.
137
+ # a member. Such a member is read as it was created, at a boundary after
138
+ # its creation; before it, the record did not exist yet.
139
139
  #: (untyped) -> untyped
140
140
  def record_created_in(boundary)
141
141
  index = transaction_index(boundary)
142
- return unless index && versions.fetch(index).event == 'create'
142
+ return unless index
143
+
144
+ version = versions.fetch(index)
145
+ return unless version.event == 'create' && !VersionBoundary.at_or_after?(version, boundary)
143
146
 
144
147
  state_after(index)&.instantiate
145
148
  end
@@ -149,7 +152,7 @@ module PaperTrailDiff
149
152
  index = boundary_index(boundary)
150
153
  return state_for(versions.fetch(index)) if index
151
154
 
152
- @live
155
+ live
153
156
  end
154
157
 
155
158
  # A handled nil is known absence, not permission to query the current row.
@@ -170,24 +173,23 @@ module PaperTrailDiff
170
173
  #: () -> Array[PreparedRecordState]
171
174
  def states
172
175
  recorded = versions.filter_map { |version| state_for(version) }
173
- live = @live
174
- live ? [*recorded, live] : recorded
176
+ current = live
177
+ current ? [*recorded, current] : recorded
175
178
  end
176
179
 
177
- # The classes the record had at any point, or either side of one version.
180
+ # The classes the record had at any point, or either side of one version:
181
+ # a create has no state before it and a destroy none after.
178
182
  #: (?untyped) -> Array[untyped]
179
183
  def model_classes(version = nil)
180
184
  return states.map(&:model_class) unless version
181
185
 
182
- states_around(version).map(&:model_class)
186
+ states_across(version, version).map(&:model_class)
183
187
  end
184
188
 
185
- # The states either side of one version; a create has none before it and a
186
- # destroy none after.
187
- #: (untyped) -> Array[PreparedRecordState]
188
- def states_around(version)
189
- index = @version_positions.fetch(version.id.to_s)
190
- [state_for(version), state_after(index)].compact
189
+ # The states before `first` and after `last`, where they exist.
190
+ #: (untyped, untyped) -> Array[PreparedRecordState]
191
+ def states_across(first, last)
192
+ [state_for(first), state_after(@version_positions.fetch(last.id.to_s))].compact
191
193
  end
192
194
 
193
195
  #: (untyped) -> [PreparedRecordState, PreparedRecordState]?
@@ -204,7 +206,9 @@ module PaperTrailDiff
204
206
 
205
207
  private
206
208
 
209
+ # @rbs @times: Array[untyped]
207
210
  # @rbs @live: PreparedRecordState?
211
+ # @rbs @live_record: untyped
208
212
  # @rbs @state_loader: PreparedVersionStateLoader
209
213
  # @rbs @states: Hash[untyped, PreparedRecordState?]
210
214
  # @rbs @version_positions: Hash[String, Integer]
@@ -213,7 +217,16 @@ module PaperTrailDiff
213
217
  #: (Integer) -> PreparedRecordState?
214
218
  def state_after(index)
215
219
  successor = versions[index + 1]
216
- successor ? state_for(successor) : @live
220
+ successor ? state_for(successor) : live
221
+ end
222
+
223
+ #: () -> PreparedRecordState?
224
+ def live
225
+ record = @live_record
226
+ return @live unless record
227
+
228
+ @live_record = nil
229
+ @live = PreparedRecordState.new(record)
217
230
  end
218
231
 
219
232
  # A version is eligible when it is at or after the boundary, or shares the
@@ -224,11 +237,14 @@ module PaperTrailDiff
224
237
  # "At or after" is decided by the version order rather than the timestamp
225
238
  # alone. A version written in the same instant as the boundary but before
226
239
  # it already took effect there; reading its pre-change state would put the
227
- # boundary on the wrong side of a change it follows.
240
+ # boundary on the wrong side of a change it follows. Each time is read
241
+ # once, since every record is placed against every boundary.
228
242
  #: (untyped) -> Integer?
229
243
  def boundary_index(boundary)
230
- chronological = versions.bsearch_index do |candidate|
231
- VersionBoundary.at_or_after?(candidate, boundary)
244
+ boundary_time = boundary.created_at
245
+ chronological = (0...versions.length).bsearch do |index|
246
+ VersionBoundary.at_or_after?(versions.fetch(index), boundary,
247
+ time: @times.fetch(index), boundary_time: boundary_time)
232
248
  end
233
249
  transactional = transaction_index(boundary)
234
250
  return chronological unless transactional
@@ -263,7 +279,8 @@ module PaperTrailDiff
263
279
  prepared = @state_loader.call(version)
264
280
  return @states[version.id] = prepared if prepared
265
281
 
266
- record = version.reify(
282
+ record = Support.reify(
283
+ version,
267
284
  dup: true,
268
285
  has_many: false,
269
286
  has_one: false,
@@ -308,6 +325,15 @@ module PaperTrailDiff
308
325
  ids.each { |id| add_series(model_class, id, grouped, live) }
309
326
  end
310
327
 
328
+ # The transactions the versions held from the start onward belong to that
329
+ # began before it, and where the earliest of them began; see
330
+ # PreparedHistoryLoader. Nothing when none did.
331
+ #: () -> [Array[Array[untyped]], untyped]?
332
+ def opening
333
+ start = @start_time
334
+ start && OpeningTransactions.new(@series, start).call
335
+ end
336
+
311
337
  #: (untyped, untyped, untyped) -> untyped
312
338
  def record_before(model_class, id, boundary)
313
339
  @series.fetch(identity(model_class, id)).record_before(boundary)
@@ -326,8 +352,7 @@ module PaperTrailDiff
326
352
  state = series.state_before(boundary)
327
353
  return [true, nil] unless state
328
354
 
329
- @direct_states[state] = @direct_loader.complete(state) unless @direct_states.key?(state)
330
- prepared = @direct_states[state]
355
+ prepared = direct_state(state)
331
356
  [!prepared.nil?, prepared]
332
357
  end
333
358
 
@@ -348,7 +373,7 @@ module PaperTrailDiff
348
373
  return [false, nil] unless handled
349
374
  return [true, state] unless direct && state
350
375
 
351
- prepared = @direct_loader.complete(state)
376
+ prepared = direct_state(state)
352
377
  [!prepared.nil?, prepared]
353
378
  end
354
379
 
@@ -362,7 +387,7 @@ module PaperTrailDiff
362
387
  plain_reader = generated_reader?(model_class, name)
363
388
  ids.flat_map do |id|
364
389
  @series.fetch(identity(model_class, id)).states.map do |state|
365
- direct = @direct_loader.complete(state) if plain_reader
390
+ direct = direct_state(state) if plain_reader
366
391
  direct ? direct.attributes[name] : state.instantiate.public_send(name)
367
392
  end
368
393
  end
@@ -373,14 +398,22 @@ module PaperTrailDiff
373
398
  @series.fetch(identity(model_class, id)).versions
374
399
  end
375
400
 
401
+ #: () -> Array[untyped]
402
+ def versions
403
+ @series.each_value.flat_map(&:versions)
404
+ end
405
+
376
406
  #: (untyped, untyped, ?untyped) -> Array[untyped]
377
407
  def model_classes(model_class, id, version = nil)
378
408
  @series.fetch(identity(model_class, id)).model_classes(version)
379
409
  end
380
410
 
381
- #: (untyped, untyped, untyped) -> Array[PreparedRecordState]
382
- def states_around(model_class, id, version)
383
- @series.fetch(identity(model_class, id)).states_around(version)
411
+ # The attributes before `first` and after `last`, where they exist, typed
412
+ # as a reified record's are.
413
+ #: (untyped, untyped, untyped, untyped) -> Array[Hash[untyped, untyped]]
414
+ def typed_states_across(model_class, id, first, last)
415
+ @series.fetch(identity(model_class, id)).states_across(first, last)
416
+ .map { |state| typed_attributes(state) }
384
417
  end
385
418
 
386
419
  #: (untyped, untyped) -> bool
@@ -394,13 +427,19 @@ module PaperTrailDiff
394
427
  # instantiating it, as reify does.
395
428
  #: (PreparedRecordState) -> Hash[untyped, untyped]
396
429
  def typed_attributes(state)
397
- @direct_states[state] = @direct_loader.complete(state) unless @direct_states.key?(state)
398
- typed = @direct_states[state]
430
+ typed = direct_state(state)
399
431
  return typed.attributes if typed
400
432
 
401
433
  PreparedRecordState.new(state.instantiate).attributes
402
434
  end
403
435
 
436
+ # A state completed as a record of its class would hold it, or nil where
437
+ # only instantiating can tell; each state is completed once.
438
+ #: (PreparedRecordState) -> PreparedRecordState?
439
+ def direct_state(state)
440
+ @direct_states.fetch(state) { @direct_states[state] = @direct_loader.complete(state) }
441
+ end
442
+
404
443
  #: (untyped, String) -> bool
405
444
  def generated_reader?(model, name)
406
445
  model.define_attribute_methods
@@ -423,7 +462,7 @@ module PaperTrailDiff
423
462
 
424
463
  #: (untyped, untyped) -> Array[String]
425
464
  def identity(model_class, id)
426
- [model_class.base_class.name.to_s, id.to_s]
465
+ Support.record_identity(model_class, id)
427
466
  end
428
467
 
429
468
  #: (untyped, Array[untyped]) -> Array[untyped]
@@ -435,8 +474,7 @@ module PaperTrailDiff
435
474
  def add_series(model_class, id, versions, live)
436
475
  record = live[id.to_s]
437
476
  @series[identity(model_class, id)] = PreparedRecordSeries.new(
438
- versions: versions.fetch(id.to_s, []),
439
- live: record && PreparedRecordState.new(record),
477
+ versions: versions.fetch(id.to_s, []), live: nil, live_record: record,
440
478
  state_loader: @state_loader
441
479
  )
442
480
  end
@@ -444,16 +482,15 @@ module PaperTrailDiff
444
482
  # A PaperTrail version is a pre-change snapshot, so the state at the last
445
483
  # selected boundary can only live in the next version after it. One
446
484
  # trailing version per identity is retained, rather than every version
447
- # recorded between the requested range and the present.
485
+ # recorded between the requested range and the present. Each record's
486
+ # versions are read in one statement, which takes 500 records.
448
487
  #: (untyped, Array[untyped]) -> Array[untyped]
449
488
  def versions_for(model_class, ids)
450
- version_class = model_class.paper_trail.version_class
451
- scope = version_class.where(
452
- item_type: model_class.base_class.name,
453
- item_id: ids
454
- ).where(created_at: @start_time..)
455
- scope = scope.where(window_condition(version_class)) if @end_time
456
- scope.order(:id).to_a
489
+ ids.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
490
+ scope = VersionQuery.for_items(model_class, slice).where(created_at: @start_time..)
491
+ scope = scope.where(window_condition(model_class.paper_trail.version_class)) if @end_time
492
+ scope.order(:id).to_a
493
+ end
457
494
  end
458
495
 
459
496
  # In range, or the earliest version after it, resolved in the same query
@@ -481,7 +518,64 @@ module PaperTrailDiff
481
518
  primary_key = model_class.primary_key
482
519
  return [] if primary_key.is_a?(Array)
483
520
 
484
- model_class.base_class.unscoped.where(primary_key => ids).to_a
521
+ ids.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
522
+ model_class.base_class.unscoped.where(primary_key => slice).to_a
523
+ end
524
+ end
525
+ end
526
+
527
+ # Finds the transactions that crossed a history's start: those the versions
528
+ # held from the start onward belong to that also saved versions before it,
529
+ # of any record. One statement per 500 transactions.
530
+ class OpeningTransactions
531
+ #: (Hash[Array[String], PreparedRecordSeries], untyped) -> void
532
+ def initialize(series, start)
533
+ @series = series
534
+ @start = start
535
+ end
536
+
537
+ # Their keys, as ActivityTransactionGroups keys a version's, and when the
538
+ # earliest began; nil when none crossed the start.
539
+ #: () -> [Array[Array[untyped]], untyped]?
540
+ def call
541
+ began = transactions.flat_map do |version_class, ids|
542
+ earliest(version_class, ids).map { |id, at| [[version_class.name, id], at] }
543
+ end
544
+ return if began.empty?
545
+
546
+ [began.map(&:first), began.map(&:last).min]
547
+ end
548
+
549
+ private
550
+
551
+ # When each of these transactions saved its first version before the
552
+ # start, for those that saved one there.
553
+ #: (untyped, Array[untyped]) -> Array[[untyped, untyped]]
554
+ def earliest(version_class, transaction_ids)
555
+ before = version_class.arel_table[:created_at].lt(@start)
556
+ transaction_ids.each_slice(Support::IDS_PER_STATEMENT).flat_map do |slice|
557
+ version_class.where(transaction_id: slice).where(before).group(:transaction_id)
558
+ .minimum(:created_at).to_a
559
+ end
560
+ end
561
+
562
+ # @rbs @series: Hash[Array[String], PreparedRecordSeries]
563
+ # @rbs @start: untyped
564
+
565
+ # The transactions of the versions held from the start onward, by version
566
+ # class, since each version table numbers its own.
567
+ #: () -> Hash[untyped, Array[untyped]]
568
+ def transactions
569
+ found = {} #: Hash[untyped, Array[untyped]]
570
+ @series.each_value do |series|
571
+ series.versions.each do |version|
572
+ transaction_id = VersionBoundary.transaction_id(version)
573
+ next unless transaction_id && version.created_at >= @start
574
+
575
+ (found[version.class] ||= []) << transaction_id
576
+ end
577
+ end
578
+ found.transform_values(&:uniq)
485
579
  end
486
580
  end
487
581
  end
@@ -20,6 +20,22 @@ module PaperTrailDiff
20
20
  build(state, boundary, tree, normalizer, history, path: '')
21
21
  end
22
22
 
23
+ # The state `call` builds a version's snapshot from, or nil when the
24
+ # version stored none or must be reified.
25
+ #: (untyped) -> PreparedRecordState?
26
+ def state(version)
27
+ @loader.call(version) if version.object
28
+ end
29
+
30
+ # The current row of a root, given as its state, with its associations as
31
+ # `boundary` reads them. Its attributes are the record's own, as the record
32
+ # path normalizes them, so its model need not be plain; its members are
33
+ # read as a version's are.
34
+ #: (PreparedRecordState, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> [bool, RecordSnapshot?]
35
+ def live(state, boundary, tree:, normalizer:, history:)
36
+ build(state, boundary, tree, normalizer, history, path: '')
37
+ end
38
+
23
39
  private
24
40
 
25
41
  # @rbs @traversal: AssociationTraversal