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
@@ -0,0 +1,146 @@
1
+ # frozen_string_literal: true
2
+ # rbs_inline: enabled
3
+
4
+ module PaperTrailDiff
5
+ # Reads each value as the database stores it.
6
+ #
7
+ # PaperTrail writes a version from the instance in memory, which can hold a
8
+ # value more exactly than its column does: a record saved twice through one
9
+ # instance records the value as Ruby held it, and every later version as the
10
+ # row gave it back. The two would compare as an edit nobody made. Each side
11
+ # is brought to the form the column keeps, which leaves a value read from
12
+ # the row as it is:
13
+ #
14
+ # - a time in a column without a declared precision, which Active Record
15
+ # writes with six fractional digits, and SQL Server's `datetime` rounds
16
+ # to 1/300 s;
17
+ # - a fixed-width string, which PostgreSQL and SQL Server pad with spaces
18
+ # and MySQL reads back without trailing spaces;
19
+ # - MySQL's single-precision `float`, which reads back with six significant
20
+ # digits;
21
+ # - a decimal on SQLite, which stores it as a double.
22
+ #
23
+ # Other columns are read as they are; docs/reference.md lists the limit.
24
+ module StoredForm
25
+ MICROSECOND_DIGITS = 6
26
+ SQL_SERVER_DATETIME_STEPS = 300
27
+ FIXED_WIDTH = /\A(?:n?char|character)\(\d+\)\z/i
28
+ INT64 = 2**63
29
+ private_constant :MICROSECOND_DIGITS, :SQL_SERVER_DATETIME_STEPS, :FIXED_WIDTH, :INT64
30
+
31
+ @forms = {} #: Hash[untyped, Hash[String, ^(untyped) -> untyped]]
32
+
33
+ #: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
34
+ def self.apply(model_class, attributes)
35
+ forms = forms(model_class)
36
+ return attributes if forms.empty?
37
+
38
+ attributes.to_h do |name, value|
39
+ form = forms[name.to_s]
40
+ [name, form && !value.nil? ? form.call(value) : value]
41
+ end
42
+ end
43
+
44
+ # The form each column of the model's table needs, by name.
45
+ #: (untyped) -> Hash[String, ^(untyped) -> untyped]
46
+ def self.forms(model_class)
47
+ known = @forms #: Hash[untyped, Hash[String, ^(untyped) -> untyped]]
48
+ known.fetch(model_class) do
49
+ adapter = model_class.connection_db_config.adapter.to_s
50
+ forms = {} #: Hash[String, ^(untyped) -> untyped]
51
+ model_class.columns.each do |column|
52
+ form = form(adapter, column, model_class.type_for_attribute(column.name))
53
+ forms[column.name] = form if form
54
+ end
55
+ known[model_class] = forms.freeze
56
+ end
57
+ end
58
+ private_class_method :forms
59
+
60
+ #: (String, untyped, untyped) -> (^(untyped) -> untyped)?
61
+ def self.form(adapter, column, type)
62
+ case column.type
63
+ when :datetime, :timestamp, :time then time_form(adapter, column, type)
64
+ when :float then float_form(adapter, column)
65
+ when :decimal then decimal_form(adapter, type)
66
+ else fixed_width_form(adapter, column)
67
+ end
68
+ end
69
+ private_class_method :form
70
+
71
+ # Active Record truncates a time to a declared precision itself.
72
+ #: (String, untyped, untyped) -> (^(untyped) -> untyped)?
73
+ def self.time_form(adapter, column, type)
74
+ return if type.respond_to?(:precision) && type.precision
75
+ if adapter == 'sqlserver' && column.sql_type.casecmp?('datetime')
76
+ return ->(value) { sql_server_datetime(value) }
77
+ end
78
+
79
+ return if adapter == 'sqlserver'
80
+
81
+ lambda { |value|
82
+ StoredTimePrecision.truncate(value, MICROSECOND_DIGITS)
83
+ }
84
+ end
85
+ private_class_method :time_form
86
+
87
+ # SQL Server's `datetime` keeps steps of 1/300 s, read back to the
88
+ # millisecond, and rounds to the nearest.
89
+ #: (untyped) -> untyped
90
+ def self.sql_server_datetime(value)
91
+ return value unless value.is_a?(Time)
92
+
93
+ time = value #: untyped
94
+ steps = (time.subsec * SQL_SERVER_DATETIME_STEPS).round
95
+ milliseconds = Rational((steps * 1000r / SQL_SERVER_DATETIME_STEPS).round, 1000)
96
+ time.change(nsec: 0) + milliseconds
97
+ end
98
+ private_class_method :sql_server_datetime
99
+
100
+ # MySQL's `float` is single precision, read back with six digits.
101
+ #: (String, untyped) -> (^(untyped) -> untyped)?
102
+ def self.float_form(adapter, column)
103
+ return unless %w[mysql2 trilogy].include?(adapter) && column.sql_type.casecmp?('float')
104
+
105
+ lambda do |value|
106
+ if value.is_a?(Float) && value.finite?
107
+ Float(format('%.6g',
108
+ [value].pack('f').unpack1('f')))
109
+ else
110
+ value
111
+ end
112
+ end
113
+ end
114
+ private_class_method :float_form
115
+
116
+ # SQLite keeps a decimal as a double, or as an integer when it is a whole
117
+ # number that fits one, and Active Record casts what it reads back.
118
+ #: (String, untyped) -> (^(untyped) -> untyped)?
119
+ def self.decimal_form(adapter, type)
120
+ return unless adapter == 'sqlite3'
121
+
122
+ lambda do |value|
123
+ number = value #: untyped
124
+ return number unless number.is_a?(Numeric)
125
+
126
+ stored = Float(number) #: Float
127
+ stored = stored.to_i if stored.finite? && stored == stored.truncate && stored.abs < INT64
128
+ type.cast(stored)
129
+ end
130
+ end
131
+ private_class_method :decimal_form
132
+
133
+ #: (String, untyped) -> (^(untyped) -> untyped)?
134
+ def self.fixed_width_form(adapter, column)
135
+ return unless FIXED_WIDTH.match?(column.sql_type) && column.limit
136
+
137
+ if %w[mysql2 trilogy].include?(adapter)
138
+ ->(value) { value.is_a?(String) ? value.sub(/ +\z/, '') : value }
139
+ elsif %w[postgresql sqlserver].include?(adapter)
140
+ width = column.limit
141
+ ->(value) { value.is_a?(String) ? value.ljust(width) : value }
142
+ end
143
+ end
144
+ private_class_method :fixed_width_form
145
+ end
146
+ end
@@ -14,17 +14,16 @@ module PaperTrailDiff
14
14
  # side is read in one form: a `serialize`d value as JSON writes it, and a
15
15
  # binary value as its bytes. Both leave a value read from history as it is.
16
16
  module StoredJsonValues
17
- SERIALIZED_TYPE = 'ActiveRecord::Type::Serialized'
18
17
  BINARY_TYPE = 'ActiveModel::Type::Binary'
19
18
  BINARY_KEYS = ['value'].freeze
20
- private_constant :SERIALIZED_TYPE, :BINARY_TYPE, :BINARY_KEYS
19
+ private_constant :BINARY_TYPE, :BINARY_KEYS
21
20
 
22
21
  # For a model whose history is JSON, which StoredTimePrecision.digits
23
22
  # tells: a `json` or `jsonb` object column, or the JSON serializer.
24
23
  #: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
25
24
  def self.apply(model_class, attributes)
26
25
  if StoredTimePrecision.json_column?(model_class.paper_trail.version_class, 'object')
27
- convert(model_class, attributes, SERIALIZED_TYPE, &:as_json)
26
+ convert(model_class, attributes, Support::SERIALIZED_TYPE, &:as_json)
28
27
  else
29
28
  convert(model_class, attributes, BINARY_TYPE) { |value| bytes(value) }
30
29
  end
@@ -35,9 +34,13 @@ module PaperTrailDiff
35
34
  #: (untyped, Hash[untyped, untyped], String) { (untyped) -> untyped } -> Hash[untyped, untyped]
36
35
  def self.convert(model_class, attributes, type_name)
37
36
  type = Support.constant(type_name)
38
- attributes.to_h do |name, value|
39
- [name, model_class.type_for_attribute(name).is_a?(type) ? yield(value) : value]
37
+ converted = attributes.dup
38
+ model_class.attribute_types.each do |name, attribute_type|
39
+ next unless attribute_type.is_a?(type) && attributes.key?(name)
40
+
41
+ converted[name] = yield(attributes.fetch(name))
40
42
  end
43
+ converted
41
44
  end
42
45
  private_class_method :convert
43
46
 
@@ -4,27 +4,35 @@
4
4
  module PaperTrailDiff
5
5
  # Matches time values to the precision PaperTrail actually stored.
6
6
  #
7
- # PaperTrail's JSON serializer, and a `json` or `jsonb` object column, write
8
- # times through ActiveSupport's JSON encoder, which keeps only
9
- # `ActiveSupport::JSON::Encoding.time_precision` fractional digits
10
- # (milliseconds by default). The live row keeps the database's precision, so
11
- # comparing the two would report every timestamp as changed even though
12
- # nothing was edited. Truncating every side to the stored precision is
13
- # idempotent, so values that came from history are unaffected and only the
14
- # digits history could never have held are dropped.
7
+ # PaperTrail's JSON serializer, a custom serializer that writes JSON, and a
8
+ # `json` or `jsonb` object column write times as text, which keeps only as
9
+ # many fractional digits as the encoder writes: milliseconds by default,
10
+ # whole seconds in Active Support's legacy format. The live row keeps the
11
+ # database's precision, so comparing the two would report every timestamp
12
+ # as changed even though nothing was edited. Truncating every side to the
13
+ # stored precision is idempotent, so values that came from history are
14
+ # unaffected and only the digits history could never have held are dropped.
15
+ #
16
+ # The digits are read by storing a time the way history does and reading
17
+ # it back, rather than assumed from the serializer's name, so a wrapper of
18
+ # the JSON serializer and the legacy format are read as they write.
15
19
  module StoredTimePrecision
16
20
  NANOSECOND_DIGITS = 9
17
21
  JSON_COLUMN_TYPES = %i[json jsonb].freeze
18
- private_constant :NANOSECOND_DIGITS, :JSON_COLUMN_TYPES
22
+ PROBE = Time.utc(2001, 2, 3, 4, 5, 6, Rational(123_456_789, 1000)).freeze
23
+ private_constant :NANOSECOND_DIGITS, :JSON_COLUMN_TYPES, :PROBE
24
+
25
+ @written = {} #: Hash[untyped, Integer?]
19
26
 
20
27
  # Fractional digits a model's history keeps for times, or nil when the
21
- # history is stored losslessly.
28
+ # history stores them whole.
22
29
  #: (untyped) -> Integer?
23
30
  def self.digits(model_class)
24
31
  return unless Support.versioned?(model_class)
25
- return unless json_history?(model_class.paper_trail.version_class)
26
32
 
27
- json_time_precision
33
+ version_class = model_class.paper_trail.version_class
34
+ json_column = %w[object object_changes].any? { |name| json_column?(version_class, name) }
35
+ written_digits(json_column ? :json_column : Support.constant('PaperTrail').serializer)
28
36
  end
29
37
 
30
38
  #: (Hash[untyped, untyped], Integer?) -> Hash[untyped, untyped]
@@ -46,35 +54,61 @@ module PaperTrailDiff
46
54
  remainder.zero? ? time : time.change(nsec: time.nsec - remainder)
47
55
  end
48
56
 
49
- #: (untyped) -> bool
50
- def self.json_history?(version_class)
51
- %w[object object_changes].any? { |name| json_column?(version_class, name) } ||
52
- json_serializer?
53
- end
54
- private_class_method :json_history?
55
-
56
57
  # Whether the version table keeps this column as `json` or `jsonb`, which
57
- # PaperTrail writes without its serializer.
58
+ # PaperTrail writes without its serializer. A version that is not an
59
+ # Active Record model has no table.
58
60
  #: (untyped, String) -> bool
59
61
  def self.json_column?(version_class, name)
60
- JSON_COLUMN_TYPES.include?(version_class.columns_hash[name]&.type)
62
+ version_class.respond_to?(:columns_hash) &&
63
+ JSON_COLUMN_TYPES.include?(version_class.columns_hash[name]&.type)
61
64
  end
62
65
 
66
+ # The digits a time keeps when written as `writer` writes history, which
67
+ # can change with Active Support's JSON settings. A writer that gives a
68
+ # time back as a time keeps it whole.
69
+ #: (untyped) -> Integer?
70
+ def self.written_digits(writer)
71
+ encoding = json_encoding
72
+ key = [writer, encoding.time_precision, encoding.use_standard_json_time_format]
73
+ @written.fetch(key) { @written[key] = read_digits(written_back(writer)) }
74
+ end
75
+ private_class_method :written_digits
76
+
77
+ #: (untyped) -> untyped
78
+ def self.written_back(writer)
79
+ stored = { 'at' => PROBE }
80
+ if writer == :json_column
81
+ json = Support.constant('ActiveSupport::JSON') #: untyped
82
+ json.decode(json.encode(stored)).fetch('at')
83
+ else
84
+ writer.load(writer.dump(stored)).fetch('at')
85
+ end
86
+ rescue StandardError
87
+ nil
88
+ end
89
+ private_class_method :written_back
90
+
91
+ # The fewest digits that read the probe back, or none when it came back
92
+ # whole. Text that names no time keeps nothing to truncate to.
93
+ #: (untyped) -> Integer?
94
+ def self.read_digits(stored)
95
+ return unless stored.is_a?(String)
96
+
97
+ parser = Time #: untyped
98
+ time = parser.parse(stored).to_r
99
+ 0.upto(NANOSECOND_DIGITS).find { |digits| truncate(PROBE, digits).to_r == time }
100
+ rescue ArgumentError
101
+ nil
102
+ end
103
+ private_class_method :read_digits
104
+
63
105
  # mutant:disable - Every mutation that survives here reads the same
64
106
  # constant another way: from this module rather than Object, or with `::`.
65
- #: () -> Integer
66
- def self.json_time_precision
107
+ #: () -> untyped
108
+ def self.json_encoding
67
109
  active_support = Object.const_get(:ActiveSupport) #: untyped
68
- active_support.const_get(:JSON).const_get(:Encoding).time_precision
69
- end
70
- private_class_method :json_time_precision
71
-
72
- # Whether PaperTrail writes history with its JSON serializer.
73
- # mutant:disable - As for json_time_precision.
74
- #: () -> bool
75
- def self.json_serializer?
76
- paper_trail = Object.const_get(:PaperTrail) #: untyped
77
- paper_trail.serializer.equal?(paper_trail.const_get(:Serializers).const_get(:JSON))
110
+ active_support.const_get(:JSON).const_get(:Encoding)
78
111
  end
112
+ private_class_method :json_encoding
79
113
  end
80
114
  end
@@ -5,16 +5,48 @@ module PaperTrailDiff
5
5
  # Reads a model's attribute values in the one form every account of them
6
6
  # shares: a version decoded from history, the current row, and the changes
7
7
  # a version recorded. Each would otherwise differ where nothing was edited.
8
- # TimeOfDay puts a time of day on one date, and for JSON history,
9
- # StoredJsonValues and StoredTimePrecision read values as JSON stored them.
8
+ # TimeOfDay puts a time of day on one date, StoredForm reads a value as its
9
+ # column keeps it, and for JSON history, StoredJsonValues and
10
+ # StoredTimePrecision read values as JSON stored them.
11
+ #
12
+ # An attribute the model declares without a column, such as a form field,
13
+ # is left out: PaperTrail stores whatever the instance held in memory, but
14
+ # no row ever holds it, so it would read as values and changes the
15
+ # database never had.
10
16
  module StoredValues
17
+ @unstored = {} #: Hash[untyped, Array[String]]
18
+
11
19
  #: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
12
20
  def self.apply(model_class, attributes)
13
- attributes = TimeOfDay.apply(model_class, attributes)
21
+ attributes = attributes.except(*unstored(model_class))
22
+ attributes = StoredForm.apply(model_class, TimeOfDay.apply(model_class, attributes))
14
23
  digits = StoredTimePrecision.digits(model_class)
15
24
  return attributes unless digits
16
25
 
17
26
  StoredTimePrecision.apply(StoredJsonValues.apply(model_class, attributes), digits)
18
27
  end
28
+
29
+ # The model's attributes without a column, which a model keeps as it was
30
+ # defined, as TimeOfDay.columns does.
31
+ #: (untyped) -> Array[String]
32
+ def self.unstored(model_class)
33
+ known = @unstored #: Hash[untyped, Array[String]]
34
+ known.fetch(model_class) do
35
+ known[model_class] = (model_class.attribute_names - model_class.column_names).freeze
36
+ end
37
+ end
38
+
39
+ # A copy of the record holding `stored`, its attributes as `apply` read
40
+ # them, or the record itself where it already holds them.
41
+ #: (untyped, Hash[String, untyped]) -> untyped
42
+ def self.record(record, stored)
43
+ held = record.attributes
44
+ kept = stored.reject { |name, value| Support.same?(value, held.fetch(name)) }
45
+ return record if kept.empty?
46
+
47
+ copy = record.class.instantiate(record.attributes_before_type_cast)
48
+ kept.each { |name, value| copy[name] = value }
49
+ copy.tap(&:clear_changes_information)
50
+ end
19
51
  end
20
52
  end