paper_trail_diff 0.17.1 → 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 +648 -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 +15 -23
  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 +214 -182
  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 +12 -10
  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 +9 -16
  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 +138 -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 +11 -5
  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
@@ -37,9 +37,6 @@ module PaperTrailDiff
37
37
  # Truncating instead would hand back a report that is short without saying so.
38
38
  class BatchLimitExceededError < Error; end
39
39
 
40
- # Historical candidate loading exceeded its explicitly bounded work budget.
41
- class FilterLimitExceededError < Error; end
42
-
43
40
  # Raised when a requested ActiveRecord association does not exist.
44
41
  class UnknownAssociationError < Error; end
45
42
 
@@ -56,7 +53,4 @@ module PaperTrailDiff
56
53
  # Raised when recorded PT-AT metadata cannot reliably reconstruct a selected association,
57
54
  # or a polymorphic type names no class.
58
55
  class IncompleteAssociationHistoryError < Error; end
59
-
60
- # Raised when current-ended activity cannot be reconstructed for a selected association.
61
- class UnsupportedLiveActivityError < Error; end
62
56
  end
@@ -0,0 +1,96 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # The kind of value a column holds when its database compares it exactly
6
+ # as Ruby compares the attribute's values, which is what lets ScopeCondition
7
+ # and ScopeRanking decide a scope in Ruby. Each adapter lists the SQL types
8
+ # it compares that way, so a type it does not list, such as PostgreSQL's
9
+ # character(n) or citext, and an adapter it does not know, leave a scope
10
+ # that compares them unreadable rather than being trusted.
11
+ module ExactColumnType
12
+ # Kinds by SQL type, without its size, precision or scale. Integers,
13
+ # booleans and dates compare alike everywhere listed. Text compares
14
+ # exactly only where the database compares strings byte by byte by
15
+ # default: MySQL and SQL Server ignore case and trailing spaces, and
16
+ # PostgreSQL pads character(n). A datetime is listed where it keeps the
17
+ # value Active Record writes; SQL Server's datetime rounds it to 1/300 s.
18
+ # A time of day is not listed: in memory it keeps the date it was given,
19
+ # which the database drops.
20
+ MYSQL_TYPES = {
21
+ 'tinyint(1)' => :boolean, 'tinyint' => :integer, 'smallint' => :integer,
22
+ 'mediumint' => :integer, 'int' => :integer, 'bigint' => :integer,
23
+ 'tinyint unsigned' => :integer, 'smallint unsigned' => :integer,
24
+ 'mediumint unsigned' => :integer, 'int unsigned' => :integer, 'bigint unsigned' => :integer,
25
+ 'date' => :date, 'datetime' => :datetime, 'timestamp' => :datetime
26
+ }.freeze
27
+ SQL_TYPES = {
28
+ 'postgresql' => {
29
+ 'smallint' => :integer, 'integer' => :integer, 'bigint' => :integer,
30
+ 'boolean' => :boolean, 'character varying' => :text, 'text' => :text, 'date' => :date,
31
+ 'timestamp without time zone' => :datetime, 'timestamp with time zone' => :datetime
32
+ }.freeze,
33
+ 'sqlite3' => {
34
+ 'integer' => :integer, 'int' => :integer, 'smallint' => :integer, 'bigint' => :integer,
35
+ 'boolean' => :boolean, 'varchar' => :text, 'text' => :text, 'date' => :date,
36
+ 'datetime' => :datetime
37
+ }.freeze,
38
+ 'mysql2' => MYSQL_TYPES,
39
+ 'trilogy' => MYSQL_TYPES,
40
+ 'sqlserver' => {
41
+ 'tinyint' => :integer, 'smallint' => :integer, 'int' => :integer, 'bigint' => :integer,
42
+ 'bit' => :boolean, 'date' => :date, 'datetime2' => :datetime
43
+ }.freeze
44
+ }.freeze
45
+ # The Active Model type that casts each kind's values in Ruby, named so
46
+ # that loading needs no Active Model. An attribute type of another class,
47
+ # such as one that serializes or encrypts the column, reads no kind.
48
+ RUBY_TYPES = { integer: 'ActiveModel::Type::Integer', boolean: 'ActiveModel::Type::Boolean',
49
+ text: 'ActiveModel::Type::ImmutableString', date: 'ActiveModel::Type::Date',
50
+ datetime: 'ActiveModel::Type::DateTime' }.freeze
51
+ # Rails wraps a time-zone-aware attribute's type, by default every
52
+ # datetime's, in this delegator; the time it stores is the wrapped type's.
53
+ TIME_ZONE_TYPE = 'ActiveRecord::AttributeMethods::TimeZoneConversion::TimeZoneConverter'
54
+ private_constant :MYSQL_TYPES, :RUBY_TYPES, :TIME_ZONE_TYPE
55
+
56
+ # nil for anything but a column of the model's own table whose SQL type
57
+ # its adapter lists and whose attribute type reads that kind. Text with
58
+ # its own collation compares as that collation says, so it reads none.
59
+ #: (untyped, String?) -> Symbol?
60
+ def self.kind(model_class, name)
61
+ column = model_class.columns_hash[name]
62
+ return unless column
63
+
64
+ kind = sql_kind(model_class.connection_db_config.adapter, column.sql_type)
65
+ return unless kind && (column.collation.nil? || !:text.equal?(kind))
66
+
67
+ kind if casts?(model_class.type_for_attribute(name), kind)
68
+ end
69
+
70
+ #: (untyped, Symbol) -> bool
71
+ def self.casts?(type, kind)
72
+ stored_type(type).class.ancestors.map(&:name).include?(RUBY_TYPES.fetch(kind))
73
+ end
74
+ private_class_method :casts?
75
+
76
+ # The type of the value a column stores, under an enum or time zone
77
+ # wrapper. An enum stores what its subtype casts.
78
+ #: (untyped) -> untyped
79
+ def self.stored_type(type)
80
+ type = type.subtype if Support::ENUM_TYPE.eql?(type.class.name)
81
+ TIME_ZONE_TYPE.eql?(type.class.name) ? type.__getobj__ : type
82
+ end
83
+
84
+ # A type is listed with its size where that changes its kind, as MySQL's
85
+ # tinyint(1) holds a boolean.
86
+ #: (String, String) -> Symbol?
87
+ def self.sql_kind(adapter, sql_type)
88
+ types = SQL_TYPES[adapter]
89
+ return unless types
90
+
91
+ sql_type = sql_type.downcase
92
+ types[sql_type] || types[sql_type.sub(/\s*\([^)]+\)/, '')]
93
+ end
94
+ private_class_method :sql_kind
95
+ end
96
+ end
@@ -22,10 +22,10 @@ module PaperTrailDiff
22
22
  @live_states = {} #: Hash[identity, PreparedRecordState]
23
23
  end
24
24
 
25
- # A `start_at` is a window's (see PreparedHistoryLoader); a range of
26
- # versions starts at its first.
25
+ # A `start_at` is a window's, already moved back to its reach (see
26
+ # PreparedHistoryLoader); a range of versions starts at its first.
27
27
  #: (untyped, Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory?
28
- def prepare(record, root_versions, start_at: nil, end_at: root_versions.last.created_at)
28
+ def prepare(record, root_versions, start_at: nil, end_at: nil)
29
29
  return if @tree.empty?
30
30
 
31
31
  # A batch prepared this root with the others, including a root with no
@@ -35,11 +35,26 @@ module PaperTrailDiff
35
35
 
36
36
  PreparedHistoryLoader.new(
37
37
  record, root_ids: [record.id], root_versions: root_versions,
38
- start_at: start_at || root_versions.first.created_at, end_at: end_at, tree: @tree,
38
+ start_at: start_at || root_versions.first.created_at,
39
+ end_at: end_at || range_end(root_versions), tree: @tree,
39
40
  traversal: @traversal, live_records: [], window: !start_at.nil?
40
41
  ).call
41
42
  end
42
43
 
44
+ # Where a range of the record's ending at the version ends (see
45
+ # TransactionCut.range_end). A batch's history has asked already, and a
46
+ # root read alone reads no other record whose saves could take effect
47
+ # before its transaction's.
48
+ #: (untyped, untyped) -> untyped
49
+ def range_end_of(record, version)
50
+ return version if @tree.empty?
51
+
52
+ batched = @batched_roots[Endpoint.identity(record)]
53
+ return TransactionCut.range_end(version) unless batched
54
+
55
+ batched.transaction_ends([version]).last(version)
56
+ end
57
+
43
58
  # A `start_at` is a window's, as for `prepare`. A window's roots may have
44
59
  # no version in it, when only their descendants changed there.
45
60
  #: (Array[untyped], Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
@@ -64,15 +79,42 @@ module PaperTrailDiff
64
79
  register_batch(records, root_versions, live_records: [], start_at: start_at, end_at: end_at)
65
80
  end
66
81
 
82
+ # Where the earliest transaction open at a window's start began (see
83
+ # AssociationTraversal#reach_before). A window is read from there: a root
84
+ # destroyed just before it, by a transaction that went on to save its
85
+ # tree inside, is reported in the window.
86
+ #: (untyped, untyped) -> untyped
87
+ def reach_before(record, start_at) = @traversal.reach_before(record.class, start_at)
88
+
67
89
  # `history` is the one `prepare` returned for this root, if any.
90
+ # A snapshot read for a timeline whose transactions overlapped reads each
91
+ # record as that timeline places its transactions (see
92
+ # PreparedRecordIndex#reading), so it is kept apart from one read without.
68
93
  #: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
69
94
  def call(root_endpoint, context_endpoint, history: nil)
70
95
  key = snapshot_key(root_endpoint, context_endpoint)
96
+ ends = history_for(root_endpoint, context_endpoint, history)&.reading_ends
97
+ key += [ends] if ends
71
98
  return @snapshots[key] if @snapshots.key?(key)
72
99
 
73
100
  @snapshots[key] = uncached(root_endpoint, context_endpoint, history: history)
74
101
  end
75
102
 
103
+ # A version compared alone reads as a timeline reads it: each record as
104
+ # it stood before every transaction that had not ended at the version
105
+ # (see TransactionEnds).
106
+ #: (untyped) -> RecordSnapshot?
107
+ def at_version(version)
108
+ history = history_for(version, version, nil)
109
+ return call(version, version) unless history && !history.reading_ends
110
+
111
+ snapshot = nil #: RecordSnapshot?
112
+ history.reading(history.transaction_ends([version])) do
113
+ snapshot = call(version, version, history: history)
114
+ end
115
+ snapshot
116
+ end
117
+
76
118
  #: (untyped, untyped, ?history: PreparedHistory?) -> RecordSnapshot?
77
119
  def uncached(root_endpoint, context_endpoint, history: nil)
78
120
  custom(root_endpoint, context_endpoint, tree: @tree, normalizer: @normalizer,
@@ -81,7 +123,7 @@ module PaperTrailDiff
81
123
 
82
124
  #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot?
83
125
  def custom(root_endpoint, context_endpoint, tree:, normalizer:, history: nil)
84
- history = history_for(context_endpoint, history)
126
+ history = history_for(root_endpoint, context_endpoint, history)
85
127
  if Endpoint.version?(root_endpoint)
86
128
  return snapshot_from_version(
87
129
  root_endpoint, context_endpoint, tree: tree, normalizer: normalizer, history: history
@@ -102,21 +144,14 @@ module PaperTrailDiff
102
144
  live_state(root_endpoint)
103
145
  end
104
146
 
105
- #: (untyped, habtm_version: untyped, ?history: PreparedHistory?) -> untyped
106
- def association_reader(context_version, habtm_version:, history: nil)
107
- fallback = HistoricalAssociationReifier.new(
108
- context_version,
109
- habtm_version: habtm_version
110
- )
111
- history = history_for(context_version, history)
112
- return fallback unless history
113
-
114
- PreparedAssociationReifier.new(
115
- history,
116
- context_version,
117
- habtm_boundary: habtm_version,
118
- fallback: fallback
119
- )
147
+ # A member's snapshot at `path`, with the associations `tree` selects
148
+ # below it as the version reads them. Callers pass the root's history; a
149
+ # batch's for the version is the rest.
150
+ #: (PreparedRecordState, untyped, tree: AssociationTree, path: String, incoming: untyped, normalizer: SnapshotNormalizer, ?history: PreparedHistory?) -> RecordSnapshot
151
+ def member(state, context_version, tree:, path:, incoming:, normalizer:, history: nil) # rubocop:disable Metrics/ParameterLists
152
+ history ||= @prepared_histories[Support.row_key(context_version)]
153
+ @prepared_snapshotter.build(state, context_version, tree, normalizer, history,
154
+ path: path, incoming: incoming)
120
155
  end
121
156
 
122
157
  private
@@ -133,33 +168,40 @@ module PaperTrailDiff
133
168
  # @rbs @live_roots: Hash[identity, untyped]
134
169
  # @rbs @live_states: Hash[identity, PreparedRecordState]
135
170
 
136
- # A batch's history for the version wins over the one a caller passes.
137
- #: (untyped, PreparedHistory?) -> PreparedHistory?
138
- def history_for(context_endpoint, history)
139
- @prepared_histories[Support.row_key(context_endpoint)] || history
171
+ # The history a root is read from: the one its batch prepared for it,
172
+ # then the one a caller passes, then a batch's for the version. A batch
173
+ # prepares one history per class of its roots, and a boundary can be a
174
+ # version of a root of another class that stands in this root's tree,
175
+ # whose history never loaded this root's associations.
176
+ #: (untyped, untyped, PreparedHistory?) -> PreparedHistory?
177
+ def history_for(root_endpoint, context_endpoint, history)
178
+ @batched_roots[Endpoint.identity(root_endpoint)] || history ||
179
+ @prepared_histories[Support.row_key(context_endpoint)]
140
180
  end
141
181
 
182
+ # A history read to its root versions is read to where their
183
+ # transactions take effect (see TransactionCut.range_end).
184
+ #: (Array[untyped]) -> untyped
185
+ def range_end(root_versions) = TransactionCut.ends_at(root_versions)
186
+
142
187
  #: (Array[untyped], Array[untyped]) -> Hash[Symbol, untyped]
143
188
  def batch_payload(records, root_versions)
144
189
  { root_count: records.length, version_count: root_versions.length,
145
190
  model_type: records.first.class.base_class.name.to_s, batched: true }
146
191
  end
147
192
 
148
- #: (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> void
193
+ #: (Array[untyped], Array[untyped], ?live_records: Array[untyped], ?start_at: untyped, ?end_at: untyped) -> PreparedHistory
149
194
  def register_batch(records, root_versions, live_records: @live_graph_collector.call(records),
150
195
  start_at: nil, end_at: nil)
151
196
  history = PreparedHistoryLoader.new(
152
- records.first,
153
- root_ids: records.map(&:id),
154
- root_versions: root_versions,
155
- start_at: start_at || root_versions.map(&:created_at).min,
156
- end_at: end_at || root_versions.map(&:created_at).max,
157
- tree: @tree,
158
- traversal: @traversal,
159
- live_records: live_records,
160
- window: !start_at.nil?
197
+ records.first, root_ids: records.map(&:id), root_versions: root_versions,
198
+ start_at: start_at || root_versions.map(&:created_at).min,
199
+ end_at: end_at || range_end(root_versions),
200
+ tree: @tree, traversal: @traversal, live_records: live_records,
201
+ window: !start_at.nil?
161
202
  ).call
162
203
  register(history, records, root_versions)
204
+ history
163
205
  end
164
206
 
165
207
  # Snapshot reads find the history by root version, and `prepare` by root.
@@ -173,67 +215,30 @@ module PaperTrailDiff
173
215
  def snapshot_from_version(root_version, context_version, tree:, normalizer:, history:)
174
216
  model_class = RecordedClass.for(root_version)
175
217
  @preparer.call(model_class, historical: true)
176
- @traversal.ensure_habtm_history!(model_class, root_version)
177
- handled, snapshot = @prepared_snapshotter.call(
178
- root_version, context_version, tree: tree, normalizer: normalizer, history: history
179
- )
180
- return snapshot if handled
181
-
182
- record = Support.reify(root_version, dup: true)
183
- normalize(record, context_version, tree: tree, normalizer: normalizer,
184
- habtm_version: root_version, history: history)
218
+ @prepared_snapshotter.call(root_version, context_version, tree: tree, normalizer: normalizer,
219
+ history: history)
185
220
  end
186
221
 
187
- # Read from prepared history where it can be, as a version is, without
188
- # instantiating the root's members. Only the fallback, which writes the
189
- # members it rebuilds onto the root, needs a record of its own.
190
- #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot?
222
+ # Read from prepared history, as a version is, without instantiating the
223
+ # root's members.
224
+ #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, history: PreparedHistory?) -> RecordSnapshot
191
225
  def snapshot_from_live_root(root_record, context_version, tree:, normalizer:, history:)
192
226
  state = live_state(root_record)
193
227
  @preparer.call(state.model_class, historical: true)
194
- handled, snapshot = @prepared_snapshotter.live(
195
- state, context_version, tree: tree, normalizer: normalizer, history: history
196
- )
197
- return snapshot if handled
198
-
199
- normalize(live_root(root_record), context_version, tree: tree, normalizer: normalizer,
200
- habtm_version: context_version,
228
+ @prepared_snapshotter.live(state, context_version, tree: tree, normalizer: normalizer,
201
229
  history: history)
202
230
  end
203
231
 
204
232
  # The state of the root's row, read once for the call: every snapshot
205
- # that starts from the row starts from the same state. Reading it writes
206
- # nothing to the row, so it is read from the loaded record itself, whose
207
- # columns the current snapshot reads too.
233
+ # that starts from the row starts from the same state. A batch loaded the
234
+ # row already; otherwise it is read here, from the record whose columns
235
+ # the current snapshot reads too.
208
236
  #: (untyped) -> PreparedRecordState
209
237
  def live_state(root_record)
210
238
  identity = Endpoint.identity(root_record)
211
- @live_states[identity] ||= PreparedRecordState.new(loaded_root(root_record, identity))
212
- end
213
-
214
- # Rebuilding a version's associations writes them onto the record, so each
215
- # snapshot that does gets its own copy of the root's row, built from the
216
- # row's stored values without a query.
217
- #: (untyped) -> untyped
218
- def live_root(root_record)
219
- loaded = loaded_root(root_record, Endpoint.identity(root_record))
220
- loaded.class.instantiate(loaded.attributes_before_type_cast)
221
- end
222
-
223
- # A batch loaded the row already; otherwise it is read once, so every
224
- # snapshot of the call starts from the same row.
225
- #: (untyped, identity) -> untyped
226
- def loaded_root(root_record, identity)
227
- @live_roots[identity] ||= Endpoint.reload_record(root_record)
228
- end
229
-
230
- #: (untyped, untyped, tree: AssociationTree, normalizer: SnapshotNormalizer, habtm_version: untyped, history: PreparedHistory?) -> RecordSnapshot?
231
- def normalize(record, context_version, tree:, normalizer:, habtm_version:, history:) # rubocop:disable Metrics/ParameterLists
232
- reifier = association_reader(context_version, habtm_version: habtm_version, history: history)
233
- reflections = [] #: Array[untyped]
234
- reflections = @traversal.reflections_for(record.class, tree, path: '') if record
235
- reifier.reify(record, reflections) if record && !reflections.empty?
236
- normalizer.call(record, reifier: reifier)
239
+ @live_states[identity] ||= PreparedRecordState.new(
240
+ @live_roots[identity] || Endpoint.reload_record(root_record)
241
+ )
237
242
  end
238
243
 
239
244
  #: (untyped, untyped) -> Array[untyped]
@@ -18,13 +18,5 @@ module PaperTrailDiff
18
18
  &block
19
19
  )
20
20
  end
21
-
22
- # Reports a condition rather than timing work: nothing failed, but the
23
- # result may be incomplete and only the application can judge that.
24
- #: (String | Symbol, Hash[Symbol, untyped]) -> void
25
- def notify(event, payload)
26
- instrument(event, payload) { nil }
27
- nil
28
- end
29
21
  end
30
22
  end
@@ -61,10 +61,7 @@ module PaperTrailDiff
61
61
  #: (untyped, AssociationTree) -> Array[[untyped, AssociationTree]]
62
62
  def selected_reflections(model_class, tree)
63
63
  tree.children.map do |name, subtree|
64
- reflection = model_class.reflect_on_association(name)
65
- raise ConfigurationError, "unknown association: #{name}" unless reflection
66
-
67
- [reflection, subtree]
64
+ [model_class.reflect_on_association(name), subtree]
68
65
  end
69
66
  end
70
67
 
@@ -33,9 +33,7 @@ module PaperTrailDiff
33
33
  #: (untyped, Array[untyped], AssociationTree, path: String, into: Hash[Array[untyped], untyped]) -> void
34
34
  def collect_group(model_class, records, tree, path:, into:)
35
35
  @traversal.reflections_for(model_class, tree, path: path).each do |reflection|
36
- subtree = tree.child(reflection.name)
37
- next unless subtree
38
-
36
+ subtree = tree.child(reflection.name) #: AssociationTree
39
37
  child_path = Support.association_path(path, reflection.name)
40
38
  collect(children_for(records, reflection), subtree, path: child_path, into: into)
41
39
  end
@@ -41,7 +41,6 @@ module PaperTrailDiff
41
41
  private_constant :Absent
42
42
 
43
43
  ABSENT = Absent.new.freeze
44
-
45
44
  #: (untyped, untyped) -> nested_changes
46
45
  def self.call(from_value, to_value)
47
46
  new(from_value, to_value).call
@@ -58,6 +57,38 @@ module PaperTrailDiff
58
57
  end
59
58
  end
60
59
 
60
+ # The comparable value as a Hash key: two values Support.same? reads
61
+ # alike are one key, as the attribute diff and the walk through a hash
62
+ # read them. A Hash looks its keys up with `eql?`, which also tells an
63
+ # Integer from a BigDecimal of the same value, so every number is read as
64
+ # a rational beside whether it is a Float, at any depth. One that is not
65
+ # finite has no rational: an infinity keeps its sign, and every NaN is one
66
+ # key, as a database stores it.
67
+ #: (untyped) -> untyped
68
+ def self.countable(value)
69
+ case value
70
+ when Hash then string_keyed(value) { |item| countable(item) }
71
+ when Array then value.map { |item| countable(item) }
72
+ when Numeric then number_key(value)
73
+ else value
74
+ end
75
+ end
76
+
77
+ #: (Numeric) -> untyped
78
+ def self.number_key(number)
79
+ [number.instance_of?(Float), rational(number)]
80
+ end
81
+ private_class_method :number_key
82
+
83
+ # The number as a rational, or as it is when it has none: a complex
84
+ # number or an infinity. A NaN, which equals nothing, reads as nil.
85
+ #: (untyped) -> untyped
86
+ def self.rational(number)
87
+ return if Support.nan?(number)
88
+
89
+ number.real? && number.finite? ? number.to_r : number
90
+ end
91
+
61
92
  # The hash keyed by name, each value as the block returns it. Two keys
62
93
  # with one name, such as `:a` and `"a"`, cannot both be kept.
63
94
  #: (Hash[untyped, untyped]) { (untyped) -> untyped } -> Hash[String, untyped]
@@ -129,18 +160,19 @@ module PaperTrailDiff
129
160
  keys(from_hash, to_hash).each do |key|
130
161
  from_item = from_hash.fetch(key, ABSENT)
131
162
  to_item = to_hash.fetch(key, ABSENT)
132
- next if from_item == to_item
133
-
134
- here = (path + [key]).freeze
135
- if from_item.is_a?(Hash) && to_item.is_a?(Hash)
136
- walk(from_item, to_item, here, changes)
137
- else
138
- change = change_for(from_item, to_item)
139
- changes[here] = change if change
140
- end
163
+ visit(from_item, to_item, (path + [key]).freeze, changes) unless Support.same?(from_item,
164
+ to_item)
141
165
  end
142
166
  end
143
167
 
168
+ #: (untyped, untyped, Array[String], nested_changes) -> void
169
+ def visit(from_item, to_item, here, changes)
170
+ return walk(from_item, to_item, here, changes) if from_item.is_a?(Hash) && to_item.is_a?(Hash)
171
+
172
+ change = change_for(from_item, to_item)
173
+ changes[here] = change if change
174
+ end
175
+
144
176
  #: (Hash[untyped, untyped]) -> Hash[String, untyped]
145
177
  def normalize_keys(hash)
146
178
  NestedComparator.string_keyed(hash, &:itself)