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
@@ -16,9 +16,18 @@ module PaperTrailDiff
16
16
  # under the wrapper's tag; any other wraps its time, and decodes as nil.
17
17
  TIME_VALUE = 'ActiveRecord::Type::Time::Value'
18
18
 
19
+ # Active Record's types for a `serialize`d attribute and for an enum,
20
+ # named so that loading needs no Active Record.
21
+ SERIALIZED_TYPE = 'ActiveRecord::Type::Serialized'
22
+ ENUM_TYPE = 'ActiveRecord::Enum::EnumType'
23
+
19
24
  # The date a database gives a time of day it reads back.
20
25
  TIME_OF_DAY_DATE = { year: 2000, month: 1, day: 1 }.freeze #: Hash[Symbol, Integer]
21
26
 
27
+ # Where a hash has no value for a key the other has (see .same?).
28
+ MISSING = Object.new.freeze
29
+ private_constant :MISSING
30
+
22
31
  # Answers a question about `value` once for each Active Record class, in
23
32
  # `answers`: its respond_to? also looks through the instance's attributes,
24
33
  # which costs more than most of what reading a version does, and every
@@ -34,30 +43,64 @@ module PaperTrailDiff
34
43
 
35
44
  # Stored attributes or changes ready for PaperTrail to decode: keyed by
36
45
  # name, with each time of day unwrapped, which then decodes as any value
37
- # does. A change's values are a pair.
38
- #: (Hash[untyped, untyped]) -> Hash[String, untyped]
39
- def self.decodable(stored)
40
- stored.to_h { |name, value| [name.to_s, unwrapped_time(value)] }
46
+ # does. A change's values are a pair. JSON history keeps a time of day as
47
+ # the text of the time it was assigned, date and offset included, which
48
+ # decoding would read on 2000-01-01 in that offset; it is read as a time
49
+ # first, so that its clock is taken on its own date, as the row's was.
50
+ #: (Hash[untyped, untyped], untyped) -> Hash[String, untyped]
51
+ def self.decodable(stored, model_class)
52
+ times = TimeOfDay.columns(model_class)
53
+ datetimes = TimeOfDay.datetime_columns(model_class)
54
+ stored.to_h do |name, value|
55
+ name = name.to_s
56
+ value = DatabaseTime.stored(value) if datetimes.include?(name)
57
+ [name, unwrapped_time(value, times.include?(name))]
58
+ end
41
59
  end
42
60
 
43
- #: (untyped) -> untyped
44
- def self.unwrapped_time(value)
45
- return value.map { |item| unwrapped_time(item) } if value.instance_of?(Array)
61
+ #: (untyped, bool) -> untyped
62
+ def self.unwrapped_time(value, time_of_day)
63
+ return value.map { |item| unwrapped_time(item, time_of_day) } if value.instance_of?(Array)
64
+ return written_time(value) if time_of_day && value.is_a?(String)
46
65
 
47
66
  TIME_VALUE.eql?(value.class.name) ? recorded_time(value) : value
48
67
  end
49
68
  private_class_method :unwrapped_time
50
69
 
70
+ # The time JSON wrote, or the text as it is when it names none.
71
+ #: (String) -> untyped
72
+ def self.written_time(text)
73
+ parser = Time #: untyped
74
+ time_of_day(parser.iso8601(text))
75
+ rescue ArgumentError
76
+ text
77
+ end
78
+ private_class_method :written_time
79
+
51
80
  # The time a stored wrapper holds -- the one it wraps, or the `@time`
52
81
  # PaperTrail reads -- on 2000-01-01, as the database keeps a time of day.
53
82
  # Active Record keeps the date of a time assigned in memory, which
54
83
  # PaperTrail stores, but the row holds only the time.
55
84
  #: (untyped) -> untyped
56
85
  def self.recorded_time(value)
57
- value.__getobj__ { value.instance_variable_get(:@time) }&.change(**TIME_OF_DAY_DATE)
86
+ time = value.__getobj__ { value.instance_variable_get(:@time) }
87
+ time && time_of_day(time)
58
88
  end
59
89
  private_class_method :recorded_time
60
90
 
91
+ # A time of day on 2000-01-01, as the database gives it back. A time with
92
+ # a zone keeps it. A plain time is stored as its clock reads in Active
93
+ # Record's default time zone, and read back on that date there, where a
94
+ # local zone can have another offset: a summer time read back in winter.
95
+ #: (untyped) -> untyped
96
+ def self.time_of_day(value)
97
+ return value.change(**TIME_OF_DAY_DATE) unless value.instance_of?(Time)
98
+
99
+ local = constant('ActiveRecord').default_timezone == :local
100
+ clock = local ? value.getlocal : value.getutc #: untyped
101
+ clock.change(**TIME_OF_DAY_DATE)
102
+ end
103
+
61
104
  # PaperTrail's `reify`, with each time of day its version recorded.
62
105
  #: (untyped, **untyped) -> untyped
63
106
  def self.reify(version, **options)
@@ -68,32 +111,69 @@ module PaperTrailDiff
68
111
  # version it was rebuilt from, which PaperTrail can decode as nil. PaperTrail
69
112
  # assigns stored attributes after building the record and links it to
70
113
  # that version, PT-AT's members too, so this assigns what PaperTrail would
71
- # if it unwrapped the value. Only a version whose stored text names the
72
- # wrapper is decoded again; any other record is returned as it is.
114
+ # if it unwrapped the value, or read JSON's text as decodable does. Only a
115
+ # version whose stored text names the wrapper, or JSON history of a model
116
+ # with a time of day, is decoded again; any other record is returned as
117
+ # it is.
73
118
  #: [T] (T) -> T
74
119
  def self.with_recorded_times(record)
75
120
  version = rebuilt_from(record)
76
121
  return record unless version
77
122
 
123
+ rebuilt = record #: untyped
124
+ times = TimeOfDay.columns(rebuilt.class)
125
+ datetimes = TimeOfDay.datetime_columns(rebuilt.class)
78
126
  version.object_deserialized.each do |name, value|
79
- next unless TIME_VALUE.eql?(value.class.name)
80
-
81
- assign_recorded(record, name, recorded_time(value))
127
+ recorded = recorded_value(value, name.to_s, times, datetimes)
128
+ assign_recorded(record, name.to_s, recorded) unless recorded.equal?(value)
82
129
  end
83
130
  record
84
131
  end
85
132
 
133
+ # The value PaperTrail would assign had it read the stored one as the
134
+ # row does, or the stored value itself.
135
+ #: (untyped, String, Array[String], Array[String]) -> untyped
136
+ def self.recorded_value(value, name, times, datetimes)
137
+ if TIME_VALUE.eql?(value.class.name)
138
+ recorded_time(value)
139
+ elsif written_time?(value, name, times)
140
+ written_time(value)
141
+ elsif datetimes.include?(name)
142
+ DatabaseTime.stored(value)
143
+ else
144
+ value
145
+ end
146
+ end
147
+ private_class_method :recorded_value
148
+
149
+ # JSON writes a time of day as text.
150
+ #: (untyped, String, Array[String]) -> bool
151
+ def self.written_time?(value, name, times)
152
+ value.is_a?(String) && times.include?(name)
153
+ end
154
+ private_class_method :written_time?
155
+
86
156
  #: (untyped) -> untyped
87
157
  def self.rebuilt_from(record)
88
158
  model = record.class
89
159
  return unless model.respond_to?(:version_association_name)
90
160
 
91
161
  version = record.public_send(model.version_association_name)
92
- # A JSON column's Hash is keyed by attribute names, never this one.
93
- version if version&.object&.include?(TIME_VALUE)
162
+ object = version&.object
163
+ version if object && read_again?(object, model)
94
164
  end
95
165
  private_class_method :rebuilt_from
96
166
 
167
+ # Whether PaperTrail decodes some stored value of this object otherwise
168
+ # than the row reads it.
169
+ #: (untyped, untyped) -> bool
170
+ def self.read_again?(object, model)
171
+ # A JSON column's Hash is keyed by attribute names, never this one.
172
+ json_times = TimeOfDay.columns(model).any? && StoredTimePrecision.digits(model)
173
+ json_times || object.include?(TIME_VALUE) || DatabaseTime.stored_date?(object, model)
174
+ end
175
+ private_class_method :read_again?
176
+
97
177
  # As PaperTrail assigns a stored attribute.
98
178
  #: (untyped, String, untyped) -> void
99
179
  def self.assign_recorded(record, name, value)
@@ -105,27 +185,32 @@ module PaperTrailDiff
105
185
  end
106
186
  private_class_method :assign_recorded
107
187
 
188
+ # A frozen plain Hash or Array whose contents are all frozen is returned as
189
+ # it is rather than copied again, as each value object that holds it would.
190
+ # Ractor.shareable? answers that and remembers a yes on the object, so a
191
+ # tree passed from one value object to the next is not walked again.
108
192
  #: (untyped) -> untyped
109
193
  def self.immutable_copy(value)
110
194
  case value
111
- when Hash
112
- immutable_hash(value)
113
- when Array
114
- value.map { |item| immutable_copy(item) }.freeze
195
+ when Hash, Array
196
+ plain = value.instance_of?(Hash) || value.instance_of?(Array)
197
+ plain && Ractor.shareable?(value) ? value : copy_tree(value)
115
198
  else
116
199
  value.frozen? ? value : duplicate_and_freeze(value)
117
200
  end
118
201
  end
119
202
 
120
- #: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
121
- def self.immutable_hash(value)
122
- copy = {} #: Hash[untyped, untyped]
123
- value.each do |key, item|
124
- copy[immutable_copy(key)] = immutable_copy(item)
203
+ #: (Hash[untyped, untyped] | Array[untyped]) -> (Hash[untyped, untyped] | Array[untyped])
204
+ def self.copy_tree(value)
205
+ if value.is_a?(Hash)
206
+ copy = {} #: Hash[untyped, untyped]
207
+ value.each { |key, item| copy[immutable_copy(key)] = immutable_copy(item) }
208
+ copy.freeze
209
+ else
210
+ value.map { |item| immutable_copy(item) }.freeze
125
211
  end
126
- copy.freeze
127
212
  end
128
- private_class_method :immutable_hash
213
+ private_class_method :copy_tree
129
214
 
130
215
  #: (untyped) -> untyped
131
216
  def self.serialize(value)
@@ -143,6 +228,13 @@ module PaperTrailDiff
143
228
  end
144
229
  end
145
230
 
231
+ # Ids as strings, once each, in the order their records' ids take: an
232
+ # integer id by its value, so 2 comes before 10, and any other by its text.
233
+ #: (Array[untyped]) -> Array[String]
234
+ def self.sort_ids(ids)
235
+ ids.map(&:to_s).uniq.sort_by { |id| id.match?(/\A\d+\z/) ? [id.to_i, id] : [Float::INFINITY, id] }
236
+ end
237
+
146
238
  # Records sort by type first so that mixed id types stay comparable, then
147
239
  # naturally within one type. Ordering by the printed form instead would put
148
240
  # id 10 before id 2, which is deterministic but reads as unsorted wherever a
@@ -220,6 +312,16 @@ module PaperTrailDiff
220
312
  raise AmbiguousVersionOrderError, ambiguous_message(ambiguous)
221
313
  end
222
314
 
315
+ # The earliest of some versions of one item, as chronological_sort orders
316
+ # them. Only the versions saved at the earliest instant are compared, so a
317
+ # tie that cannot be ordered raises there, as it does inside a range, and
318
+ # one among later versions does not.
319
+ #: (Array[untyped]) -> untyped
320
+ def self.earliest_version(versions)
321
+ earliest = versions.map(&:created_at).min
322
+ chronological_sort(versions.select { |version| version.created_at == earliest }).first
323
+ end
324
+
223
325
  #: (Array[untyped]) -> Array[untyped]?
224
326
  def self.ambiguous_pair(sorted)
225
327
  sorted.each_cons(2).find do |left, right|
@@ -241,15 +343,6 @@ module PaperTrailDiff
241
343
  end
242
344
  private_class_method :version_table
243
345
 
244
- # Versions sharing a timestamp, whether or not their ids order them. PT-AT
245
- # indexes association membership per version but resolves it by timestamp,
246
- # so association state cannot be told apart across such a pair even when the
247
- # scalar sequence is perfectly recoverable.
248
- #: (Array[untyped]) -> Array[untyped]?
249
- def self.tied_timestamp_pair(versions)
250
- versions.each_cons(2).find { |left, right| left.created_at == right.created_at }
251
- end
252
-
253
346
  # Whether a model records history at all.
254
347
  #
255
348
  # PaperTrail defines `paper_trail` on every ActiveRecord model, so asking
@@ -263,6 +356,63 @@ module PaperTrailDiff
263
356
  model_class.respond_to?(:paper_trail_options) && !model_class.paper_trail_options.nil?
264
357
  end
265
358
 
359
+ # Whether two values are one, as a diff reads them: `==`, but a NaN is the
360
+ # same as a NaN, as PostgreSQL stores and compares it, though Ruby has
361
+ # NaN unequal to everything. A value a serialized attribute holds can be
362
+ # of any class, so `==` must hold both ways, which Active Support's
363
+ # Time == String does not, and a Float is not the Integer it equals: each
364
+ # is written differently, so the change is real. Hashes and arrays are
365
+ # compared by their members.
366
+ #: (untyped, untyped) -> bool
367
+ def self.same?(left, right)
368
+ return nan?(right) if nan?(left)
369
+ return same_hash?(left, right) if left.is_a?(Hash)
370
+ return same_array?(left, right) if left.is_a?(Array)
371
+
372
+ left == right && right == left && left.instance_of?(Float) == right.instance_of?(Float)
373
+ end
374
+
375
+ # A key the right side lacks reads as a value nothing else is.
376
+ #: (Hash[untyped, untyped], untyped) -> bool
377
+ def self.same_hash?(left, right)
378
+ right.is_a?(Hash) && left.length == right.length &&
379
+ left.all? { |key, value| same?(value, right.fetch(key, MISSING)) }
380
+ end
381
+
382
+ #: (Array[untyped], untyped) -> bool
383
+ def self.same_array?(left, right)
384
+ right.is_a?(Array) && left.length == right.length &&
385
+ left.zip(right).all? { |pair| same?(*pair) }
386
+ end
387
+ private_class_method :same_hash?, :same_array?
388
+
389
+ # A Float or BigDecimal NaN.
390
+ #: (untyped) -> bool
391
+ def self.nan?(value)
392
+ number = value #: untyped
393
+ number.respond_to?(:nan?) && number.nan?
394
+ end
395
+
396
+ # An option that is a switch takes only true or false, so a truthy value
397
+ # given by mistake, such as a string, is not read as one.
398
+ #: (Symbol, untyped) -> void
399
+ def self.boolean!(name, value)
400
+ raise ConfigurationError, "#{name}: must be true or false" unless [true,
401
+ false].include?(value)
402
+ end
403
+
404
+ # Why a versioned model's history holds no states, or nil. PaperTrail
405
+ # can keep versions in a table without an `object` column, and every
406
+ # state is rebuilt from that column.
407
+ #: (untyped) -> String?
408
+ def self.stateless_reason(model_class)
409
+ versions = model_class.paper_trail.version_class
410
+ return if versions.column_names.include?('object')
411
+
412
+ "#{versions.name} has no object column, so #{model_class.name} has no recorded states " \
413
+ 'to rebuild history from: add one to its version table'
414
+ end
415
+
266
416
  # `versions.item_id` is often a string column -- PaperTrail's setup for UUID
267
417
  # keys -- while the model's own key is an integer. An id read from history
268
418
  # is cast to the key's type, or the same record read once from history and
@@ -13,6 +13,7 @@ module PaperTrailDiff
13
13
  # both, which leaves a value already on that date as it is.
14
14
  module TimeOfDay
15
15
  @columns = {} #: Hash[untyped, Array[String]]
16
+ @datetime_columns = {} #: Hash[untyped, Array[String]]
16
17
 
17
18
  #: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
18
19
  def self.apply(model_class, attributes)
@@ -20,7 +21,7 @@ module PaperTrailDiff
20
21
  return attributes if columns.empty?
21
22
 
22
23
  attributes.to_h do |name, value|
23
- [name, columns.include?(name) && value ? value.change(**Support::TIME_OF_DAY_DATE) : value]
24
+ [name, columns.include?(name) && value ? Support.time_of_day(value) : value]
24
25
  end
25
26
  end
26
27
 
@@ -34,6 +35,16 @@ module PaperTrailDiff
34
35
  end
35
36
  end
36
37
  end
37
- private_class_method :columns
38
+
39
+ # The model's `datetime` columns, kept the same way.
40
+ #: (untyped) -> Array[String]
41
+ def self.datetime_columns(model_class)
42
+ known = @datetime_columns #: Hash[untyped, Array[String]]
43
+ known.fetch(model_class) do
44
+ known[model_class] = model_class.attribute_types.filter_map do |name, type|
45
+ name if type.type == :datetime
46
+ end
47
+ end
48
+ end
38
49
  end
39
50
  end
@@ -10,15 +10,63 @@ module PaperTrailDiff
10
10
  # it runs through every version saved since it began, whatever the clock
11
11
  # that dated them read, as a report through the current state does.
12
12
  class TimeRange
13
+ MICROSECOND_DIGITS = 6
14
+
13
15
  attr_reader :begin_time #: Time
14
16
  attr_reader :end_time #: Time?
17
+ # The fractional digits its edges are cut to.
18
+ attr_reader :digits #: Integer
19
+
20
+ # A window over the versions of `models`, its edges cut to the digits
21
+ # their version tables keep. Active Record cuts a time it binds to the
22
+ # precision of the column it is compared with, so an edge left finer than
23
+ # a table that keeps whole seconds would select versions in SQL by the
24
+ # cut time and in Ruby by the whole one. Tables that differ take the
25
+ # coarsest, so that every check of one window cuts it alike.
26
+ #: (untyped, Array[untyped]) -> TimeRange
27
+ def self.for(value, models)
28
+ new(value, digits: models.filter_map do |model|
29
+ stored_digits(model)
30
+ end.min || MICROSECOND_DIGITS)
31
+ end
32
+
33
+ # The fractional digits a model's version table keeps for `created_at`,
34
+ # or nil for a model without versions. A column without a precision
35
+ # keeps whatever the adapter writes, which is microseconds.
36
+ #: (untyped) -> Integer?
37
+ def self.stored_digits(model)
38
+ return unless Support.versioned?(model)
39
+
40
+ precision = model.paper_trail.version_class.type_for_attribute('created_at').precision
41
+ [precision || MICROSECOND_DIGITS, MICROSECOND_DIGITS].min
42
+ end
43
+ private_class_method :stored_digits
15
44
 
45
+ # Checks `report(since:)`, the start of the endless window it reads, as
46
+ # that window will read it, so that a message names `since`. A range
47
+ # there would become the start of another range.
16
48
  #: (untyped) -> void
17
- def initialize(value)
49
+ def self.check_since!(since)
50
+ if since.nil? || since.is_a?(Range)
51
+ raise InvalidTimeRangeError, '`since` must be a time, date, or string; for a range, ' \
52
+ 'pass it as `within:` to analyze_scope'
53
+ end
54
+
55
+ begin
56
+ new(since..)
57
+ rescue InvalidTimeRangeError
58
+ raise InvalidTimeRangeError, '`since` must be a time, date, or string'
59
+ end
60
+ end
61
+
62
+ #: (untyped, ?digits: Integer) -> void
63
+ def initialize(value, digits: MICROSECOND_DIGITS)
18
64
  unless value.is_a?(Range) && value.begin
19
65
  raise InvalidTimeRangeError, '`within` must be a Range with a beginning'
20
66
  end
21
67
 
68
+ @digits = digits
69
+
22
70
  @begin_time = coerce_time(value.begin, boundary: :begin)
23
71
  last = value.end
24
72
  @exclude_end = !last.nil? && (value.exclude_end? || calendar_date?(last))
@@ -55,6 +103,15 @@ module PaperTrailDiff
55
103
  exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
56
104
  end
57
105
 
106
+ # The window widened to start at `earliest`, where that is before it:
107
+ # what a window reads when a transaction crosses its start (see
108
+ # PreparedHistoryLoader).
109
+ #: (untyped) -> TimeRange
110
+ def widened(earliest)
111
+ start = [earliest, begin_time].min
112
+ self.class.new(Range.new(start, end_time, exclude_end?), digits: @digits)
113
+ end
114
+
58
115
  # The versions after the window; none follows an endless one.
59
116
  #: (untyped) -> untyped
60
117
  def trailing_scope(relation)
@@ -62,26 +119,26 @@ module PaperTrailDiff
62
119
  finish ? after(relation, finish) : relation.none
63
120
  end
64
121
 
65
- # Each item's earliest version after the range, keyed by item id. One row
66
- # per item comes back from a NOT EXISTS rather than a window function, so
67
- # the query stays portable; a timestamp tie keeps the lower id.
122
+ # Each item's earliest version after the range, keyed by item id. The
123
+ # versions at each item's earliest instant come back from a NOT EXISTS
124
+ # rather than a window function, so the query stays portable. A timestamp
125
+ # tie keeps the lower id when ids order it, and raises when they cannot.
68
126
  #: (untyped) -> Hash[String, untyped]
69
127
  def first_trailing_versions(relation)
70
128
  finish = end_time
71
- first = {} #: Hash[String, untyped]
72
- return first unless finish
129
+ return {} unless finish
73
130
 
74
131
  first_after = VersionQuery.no_earlier_version(relation.arel_table) do |earlier|
75
132
  after_end(earlier[:created_at], finish)
76
133
  end
77
- versions = VersionQuery.chronological(after(relation, finish).where(first_after))
78
- versions.each { |version| first[version.item_id.to_s] ||= version }
79
- first
134
+ after(relation, finish).where(first_after).group_by { |version| version.item_id.to_s }
135
+ .transform_values { |tied| Support.earliest_version(tied) }
80
136
  end
81
137
 
82
138
  private
83
139
 
84
140
  # @rbs @exclude_end: bool
141
+ # @rbs @digits: Integer
85
142
 
86
143
  #: (untyped, Time) -> untyped
87
144
  def after(relation, finish)
@@ -93,9 +150,14 @@ module PaperTrailDiff
93
150
  exclude_end? ? column.gteq(finish) : column.gt(finish)
94
151
  end
95
152
 
153
+ # Cut to the microsecond, as adapters write a time they bind, or to the
154
+ # fewer digits the versions' column keeps: a finer edge would select
155
+ # versions in SQL by the cut time but in Ruby by the whole one, and a
156
+ # version in the edge's microsecond or second would be in one method's
157
+ # window and not another's.
96
158
  #: (untyped, boundary: Symbol) -> Time
97
159
  def coerce_time(value, boundary:)
98
- time_value(value).getutc.freeze
160
+ time_value(value).getutc.floor(@digits).freeze
99
161
  rescue ArgumentError, NoMethodError, TypeError
100
162
  raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
101
163
  end
@@ -105,12 +167,24 @@ module PaperTrailDiff
105
167
  # zoned time, and without changing the caller's own value as `utc` does.
106
168
  #: (untyped) -> untyped
107
169
  def time_value(value)
108
- return zone.parse(value) || raise(ArgumentError) if value.is_a?(String)
170
+ return parse(value) if value.is_a?(String)
109
171
  return zone.local(value.year, value.month, value.day) if calendar_date?(value)
110
172
 
111
173
  value
112
174
  end
113
175
 
176
+ # A string must name a real day, which `parse` alone does not demand: it
177
+ # reads '12' as noon today and rolls 30 February into March.
178
+ #: (String) -> untyped
179
+ def parse(value)
180
+ # A part it does not name is nil, which `valid_date?` refuses as a TypeError.
181
+ parts = Date._parse(value).values_at(:year, :mon, :mday) #: Array[untyped]
182
+ year, month, day = parts
183
+ raise ArgumentError unless Date.valid_date?(year, month, day)
184
+
185
+ zone.parse(value)
186
+ end
187
+
114
188
  # An inclusive date end runs through the day: to the next one's start.
115
189
  #: (Range[untyped]) -> untyped
116
190
  def end_value(range)
@@ -35,9 +35,13 @@ module PaperTrailDiff
35
35
  # @rbs @version_scope: untyped
36
36
  # @rbs @live_endpoint: untyped
37
37
 
38
+ # Two are read, so that a tie for first that ids cannot order raises, as
39
+ # a tie inside the range does, instead of the lower id choosing the state
40
+ # the range ends in.
38
41
  #: (untyped) -> untyped
39
42
  def trailing_version(relation)
40
- VersionQuery.chronological(@time_range.trailing_scope(relation)).first
43
+ candidates = VersionQuery.chronological(@time_range.trailing_scope(relation)).limit(2)
44
+ Support.earliest_version(candidates)
41
45
  end
42
46
  end
43
47
  end
@@ -4,27 +4,21 @@
4
4
  module PaperTrailDiff
5
5
  # Selects and compares a chronological slice of a record's version history.
6
6
  class TimelineBuilder
7
- #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
7
+ #: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
9
  record, from:, to:, snapshotter:, within: nil, version_scope: nil, plan: nil,
10
- live_endpoint: nil, traversal: nil
10
+ live_endpoint: nil
11
11
  )
12
12
  @record = record
13
13
  @range = TimelineRange.new(
14
14
  record, from: from, to: to, within: within,
15
15
  version_scope: version_scope, plan: plan,
16
- live_endpoint: live_endpoint, traversal: traversal
16
+ live_endpoint: live_endpoint
17
17
  )
18
18
  @snapshotter = snapshotter
19
19
  end
20
20
 
21
- #: () -> Array[Step]
22
- def build
23
- steps, = compare_history(selected_versions)
24
- steps
25
- end
26
-
27
- # The window the range covers once its edges have moved to transactions.
21
+ # The window the range covers, as it was asked for.
28
22
  #: () -> TimeRange?
29
23
  def window
30
24
  @range.time_range
@@ -52,7 +46,7 @@ module PaperTrailDiff
52
46
  return empty_history if plan.empty?
53
47
 
54
48
  versions = plan.versions
55
- snapshots = @snapshotter.prepare(@record, versions)
49
+ snapshots = @snapshotter.prepare(@record, versions, start_at: @range.begin_time)
56
50
  steps = build_steps(plan, snapshots)
57
51
  final = plan.closes_on_destroy ? nil : snapshots.call(plan.final_endpoint)
58
52
  [steps, snapshots.call(versions.first), final]