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
@@ -32,10 +32,6 @@ module PaperTrailDiff
32
32
  # : (untyped, reifier: untyped) -> RecordSnapshot?
33
33
  def call: (untyped, reifier: untyped) -> RecordSnapshot?
34
34
 
35
- # Normalizes one member of an already selected association branch.
36
- # : (untyped, tree: AssociationTree, path: String, incoming: untyped, reifier: untyped) -> RecordSnapshot?
37
- def call_child: (untyped, tree: AssociationTree, path: String, incoming: untyped, reifier: untyped) -> RecordSnapshot?
38
-
39
35
  # Normalizes scalar attributes without traversing or loading associations.
40
36
  # : (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
41
37
  def attributes_for: (untyped, tree: AssociationTree, path: String) -> snapshot_attributes
@@ -0,0 +1,63 @@
1
+ # Generated from lib/paper_trail_diff/stored_form.rb with RBS::Inline
2
+
3
+ module PaperTrailDiff
4
+ # Reads each value as the database stores it.
5
+ #
6
+ # PaperTrail writes a version from the instance in memory, which can hold a
7
+ # value more exactly than its column does: a record saved twice through one
8
+ # instance records the value as Ruby held it, and every later version as the
9
+ # row gave it back. The two would compare as an edit nobody made. Each side
10
+ # is brought to the form the column keeps, which leaves a value read from
11
+ # the row as it is:
12
+ #
13
+ # - a time in a column without a declared precision, which Active Record
14
+ # writes with six fractional digits, and SQL Server's `datetime` rounds
15
+ # to 1/300 s;
16
+ # - a fixed-width string, which PostgreSQL and SQL Server pad with spaces
17
+ # and MySQL reads back without trailing spaces;
18
+ # - MySQL's single-precision `float`, which reads back with six significant
19
+ # digits;
20
+ # - a decimal on SQLite, which stores it as a double.
21
+ #
22
+ # Other columns are read as they are; docs/reference.md lists the limit.
23
+ module StoredForm
24
+ MICROSECOND_DIGITS: ::Integer
25
+
26
+ SQL_SERVER_DATETIME_STEPS: ::Integer
27
+
28
+ FIXED_WIDTH: ::Regexp
29
+
30
+ INT64: untyped
31
+
32
+ # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
33
+ def self.apply: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
34
+
35
+ # The form each column of the model's table needs, by name.
36
+ # : (untyped) -> Hash[String, ^(untyped) -> untyped]
37
+ def self.forms: (untyped) -> Hash[String, ^(untyped) -> untyped]
38
+
39
+ # : (String, untyped, untyped) -> (^(untyped) -> untyped)?
40
+ def self.form: (String, untyped, untyped) -> (^(untyped) -> untyped)?
41
+
42
+ # Active Record truncates a time to a declared precision itself.
43
+ # : (String, untyped, untyped) -> (^(untyped) -> untyped)?
44
+ def self.time_form: (String, untyped, untyped) -> (^(untyped) -> untyped)?
45
+
46
+ # SQL Server's `datetime` keeps steps of 1/300 s, read back to the
47
+ # millisecond, and rounds to the nearest.
48
+ # : (untyped) -> untyped
49
+ def self.sql_server_datetime: (untyped) -> untyped
50
+
51
+ # MySQL's `float` is single precision, read back with six digits.
52
+ # : (String, untyped) -> (^(untyped) -> untyped)?
53
+ def self.float_form: (String, untyped) -> (^(untyped) -> untyped)?
54
+
55
+ # SQLite keeps a decimal as a double, or as an integer when it is a whole
56
+ # number that fits one, and Active Record casts what it reads back.
57
+ # : (String, untyped) -> (^(untyped) -> untyped)?
58
+ def self.decimal_form: (String, untyped) -> (^(untyped) -> untyped)?
59
+
60
+ # : (String, untyped) -> (^(untyped) -> untyped)?
61
+ def self.fixed_width_form: (String, untyped) -> (^(untyped) -> untyped)?
62
+ end
63
+ end
@@ -13,8 +13,6 @@ module PaperTrailDiff
13
13
  # side is read in one form: a `serialize`d value as JSON writes it, and a
14
14
  # binary value as its bytes. Both leave a value read from history as it is.
15
15
  module StoredJsonValues
16
- SERIALIZED_TYPE: ::String
17
-
18
16
  BINARY_TYPE: ::String
19
17
 
20
18
  BINARY_KEYS: untyped
@@ -3,21 +3,27 @@
3
3
  module PaperTrailDiff
4
4
  # Matches time values to the precision PaperTrail actually stored.
5
5
  #
6
- # PaperTrail's JSON serializer, and a `json` or `jsonb` object column, write
7
- # times through ActiveSupport's JSON encoder, which keeps only
8
- # `ActiveSupport::JSON::Encoding.time_precision` fractional digits
9
- # (milliseconds by default). The live row keeps the database's precision, so
10
- # comparing the two would report every timestamp as changed even though
11
- # nothing was edited. Truncating every side to the stored precision is
12
- # idempotent, so values that came from history are unaffected and only the
13
- # digits history could never have held are dropped.
6
+ # PaperTrail's JSON serializer, a custom serializer that writes JSON, and a
7
+ # `json` or `jsonb` object column write times as text, which keeps only as
8
+ # many fractional digits as the encoder writes: milliseconds by default,
9
+ # whole seconds in Active Support's legacy format. The live row keeps the
10
+ # database's precision, so comparing the two would report every timestamp
11
+ # as changed even though nothing was edited. Truncating every side to the
12
+ # stored precision is idempotent, so values that came from history are
13
+ # unaffected and only the digits history could never have held are dropped.
14
+ #
15
+ # The digits are read by storing a time the way history does and reading
16
+ # it back, rather than assumed from the serializer's name, so a wrapper of
17
+ # the JSON serializer and the legacy format are read as they write.
14
18
  module StoredTimePrecision
15
19
  NANOSECOND_DIGITS: ::Integer
16
20
 
17
21
  JSON_COLUMN_TYPES: untyped
18
22
 
23
+ PROBE: untyped
24
+
19
25
  # Fractional digits a model's history keeps for times, or nil when the
20
- # history is stored losslessly.
26
+ # history stores them whole.
21
27
  # : (untyped) -> Integer?
22
28
  def self.digits: (untyped) -> Integer?
23
29
 
@@ -29,22 +35,29 @@ module PaperTrailDiff
29
35
  # : (untyped, Integer) -> untyped
30
36
  def self.truncate: (untyped, Integer) -> untyped
31
37
 
32
- # : (untyped) -> bool
33
- def self.json_history?: (untyped) -> bool
34
-
35
38
  # Whether the version table keeps this column as `json` or `jsonb`, which
36
- # PaperTrail writes without its serializer.
39
+ # PaperTrail writes without its serializer. A version that is not an
40
+ # Active Record model has no table.
37
41
  # : (untyped, String) -> bool
38
42
  def self.json_column?: (untyped, String) -> bool
39
43
 
44
+ # The digits a time keeps when written as `writer` writes history, which
45
+ # can change with Active Support's JSON settings. A writer that gives a
46
+ # time back as a time keeps it whole.
47
+ # : (untyped) -> Integer?
48
+ def self.written_digits: (untyped) -> Integer?
49
+
50
+ # : (untyped) -> untyped
51
+ def self.written_back: (untyped) -> untyped
52
+
53
+ # The fewest digits that read the probe back, or none when it came back
54
+ # whole. Text that names no time keeps nothing to truncate to.
55
+ # : (untyped) -> Integer?
56
+ def self.read_digits: (untyped) -> Integer?
57
+
40
58
  # mutant:disable - Every mutation that survives here reads the same
41
59
  # constant another way: from this module rather than Object, or with `::`.
42
- # : () -> Integer
43
- def self.json_time_precision: () -> Integer
44
-
45
- # Whether PaperTrail writes history with its JSON serializer.
46
- # mutant:disable - As for json_time_precision.
47
- # : () -> bool
48
- def self.json_serializer?: () -> bool
60
+ # : () -> untyped
61
+ def self.json_encoding: () -> untyped
49
62
  end
50
63
  end
@@ -4,10 +4,26 @@ module PaperTrailDiff
4
4
  # Reads a model's attribute values in the one form every account of them
5
5
  # shares: a version decoded from history, the current row, and the changes
6
6
  # a version recorded. Each would otherwise differ where nothing was edited.
7
- # TimeOfDay puts a time of day on one date, and for JSON history,
8
- # StoredJsonValues and StoredTimePrecision read values as JSON stored them.
7
+ # TimeOfDay puts a time of day on one date, StoredForm reads a value as its
8
+ # column keeps it, and for JSON history, StoredJsonValues and
9
+ # StoredTimePrecision read values as JSON stored them.
10
+ #
11
+ # An attribute the model declares without a column, such as a form field,
12
+ # is left out: PaperTrail stores whatever the instance held in memory, but
13
+ # no row ever holds it, so it would read as values and changes the
14
+ # database never had.
9
15
  module StoredValues
10
16
  # : (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
11
17
  def self.apply: (untyped, Hash[untyped, untyped]) -> Hash[untyped, untyped]
18
+
19
+ # The model's attributes without a column, which a model keeps as it was
20
+ # defined, as TimeOfDay.columns does.
21
+ # : (untyped) -> Array[String]
22
+ def self.unstored: (untyped) -> Array[String]
23
+
24
+ # A copy of the record holding `stored`, its attributes as `apply` read
25
+ # them, or the record itself where it already holds them.
26
+ # : (untyped, Hash[String, untyped]) -> untyped
27
+ def self.record: (untyped, Hash[String, untyped]) -> untyped
12
28
  end
13
29
  end
@@ -15,9 +15,18 @@ module PaperTrailDiff
15
15
  # under the wrapper's tag; any other wraps its time, and decodes as nil.
16
16
  TIME_VALUE: ::String
17
17
 
18
+ # Active Record's types for a `serialize`d attribute and for an enum,
19
+ # named so that loading needs no Active Record.
20
+ SERIALIZED_TYPE: ::String
21
+
22
+ ENUM_TYPE: ::String
23
+
18
24
  # The date a database gives a time of day it reads back.
19
25
  TIME_OF_DAY_DATE: Hash[Symbol, Integer]
20
26
 
27
+ # Where a hash has no value for a key the other has (see .same?).
28
+ MISSING: untyped
29
+
21
30
  # Answers a question about `value` once for each Active Record class, in
22
31
  # `answers`: its respond_to? also looks through the instance's attributes,
23
32
  # which costs more than most of what reading a version does, and every
@@ -28,12 +37,19 @@ module PaperTrailDiff
28
37
 
29
38
  # Stored attributes or changes ready for PaperTrail to decode: keyed by
30
39
  # name, with each time of day unwrapped, which then decodes as any value
31
- # does. A change's values are a pair.
32
- # : (Hash[untyped, untyped]) -> Hash[String, untyped]
33
- def self.decodable: (Hash[untyped, untyped]) -> Hash[String, untyped]
40
+ # does. A change's values are a pair. JSON history keeps a time of day as
41
+ # the text of the time it was assigned, date and offset included, which
42
+ # decoding would read on 2000-01-01 in that offset; it is read as a time
43
+ # first, so that its clock is taken on its own date, as the row's was.
44
+ # : (Hash[untyped, untyped], untyped) -> Hash[String, untyped]
45
+ def self.decodable: (Hash[untyped, untyped], untyped) -> Hash[String, untyped]
34
46
 
35
- # : (untyped) -> untyped
36
- def self.unwrapped_time: (untyped) -> untyped
47
+ # : (untyped, bool) -> untyped
48
+ def self.unwrapped_time: (untyped, bool) -> untyped
49
+
50
+ # The time JSON wrote, or the text as it is when it names none.
51
+ # : (String) -> untyped
52
+ def self.written_time: (String) -> untyped
37
53
 
38
54
  # The time a stored wrapper holds -- the one it wraps, or the `@time`
39
55
  # PaperTrail reads -- on 2000-01-01, as the database keeps a time of day.
@@ -42,6 +58,13 @@ module PaperTrailDiff
42
58
  # : (untyped) -> untyped
43
59
  def self.recorded_time: (untyped) -> untyped
44
60
 
61
+ # A time of day on 2000-01-01, as the database gives it back. A time with
62
+ # a zone keeps it. A plain time is stored as its clock reads in Active
63
+ # Record's default time zone, and read back on that date there, where a
64
+ # local zone can have another offset: a summer time read back in winter.
65
+ # : (untyped) -> untyped
66
+ def self.time_of_day: (untyped) -> untyped
67
+
45
68
  # PaperTrail's `reify`, with each time of day its version recorded.
46
69
  # : (untyped, **untyped) -> untyped
47
70
  def self.reify: (untyped, **untyped) -> untyped
@@ -50,27 +73,52 @@ module PaperTrailDiff
50
73
  # version it was rebuilt from, which PaperTrail can decode as nil. PaperTrail
51
74
  # assigns stored attributes after building the record and links it to
52
75
  # that version, PT-AT's members too, so this assigns what PaperTrail would
53
- # if it unwrapped the value. Only a version whose stored text names the
54
- # wrapper is decoded again; any other record is returned as it is.
76
+ # if it unwrapped the value, or read JSON's text as decodable does. Only a
77
+ # version whose stored text names the wrapper, or JSON history of a model
78
+ # with a time of day, is decoded again; any other record is returned as
79
+ # it is.
55
80
  # : [T] (T) -> T
56
81
  def self.with_recorded_times: [T] (T) -> T
57
82
 
83
+ # The value PaperTrail would assign had it read the stored one as the
84
+ # row does, or the stored value itself.
85
+ # : (untyped, String, Array[String], Array[String]) -> untyped
86
+ def self.recorded_value: (untyped, String, Array[String], Array[String]) -> untyped
87
+
88
+ # JSON writes a time of day as text.
89
+ # : (untyped, String, Array[String]) -> bool
90
+ def self.written_time?: (untyped, String, Array[String]) -> bool
91
+
58
92
  # : (untyped) -> untyped
59
93
  def self.rebuilt_from: (untyped) -> untyped
60
94
 
95
+ # Whether PaperTrail decodes some stored value of this object otherwise
96
+ # than the row reads it.
97
+ # : (untyped, untyped) -> bool
98
+ def self.read_again?: (untyped, untyped) -> bool
99
+
61
100
  # As PaperTrail assigns a stored attribute.
62
101
  # : (untyped, String, untyped) -> void
63
102
  def self.assign_recorded: (untyped, String, untyped) -> void
64
103
 
104
+ # A frozen plain Hash or Array whose contents are all frozen is returned as
105
+ # it is rather than copied again, as each value object that holds it would.
106
+ # Ractor.shareable? answers that and remembers a yes on the object, so a
107
+ # tree passed from one value object to the next is not walked again.
65
108
  # : (untyped) -> untyped
66
109
  def self.immutable_copy: (untyped) -> untyped
67
110
 
68
- # : (Hash[untyped, untyped]) -> Hash[untyped, untyped]
69
- def self.immutable_hash: (Hash[untyped, untyped]) -> Hash[untyped, untyped]
111
+ # : (Hash[untyped, untyped] | Array[untyped]) -> (Hash[untyped, untyped] | Array[untyped])
112
+ def self.copy_tree: (Hash[untyped, untyped] | Array[untyped]) -> (Hash[untyped, untyped] | Array[untyped])
70
113
 
71
114
  # : (untyped) -> untyped
72
115
  def self.serialize: (untyped) -> untyped
73
116
 
117
+ # Ids as strings, once each, in the order their records' ids take: an
118
+ # integer id by its value, so 2 comes before 10, and any other by its text.
119
+ # : (Array[untyped]) -> Array[String]
120
+ def self.sort_ids: (Array[untyped]) -> Array[String]
121
+
74
122
  # Records sort by type first so that mixed id types stay comparable, then
75
123
  # naturally within one type. Ordering by the printed form instead would put
76
124
  # id 10 before id 2, which is deterministic but reads as unsorted wherever a
@@ -121,6 +169,13 @@ module PaperTrailDiff
121
169
  # : (Array[untyped]) -> Array[untyped]
122
170
  def self.chronological_sort: (Array[untyped]) -> Array[untyped]
123
171
 
172
+ # The earliest of some versions of one item, as chronological_sort orders
173
+ # them. Only the versions saved at the earliest instant are compared, so a
174
+ # tie that cannot be ordered raises there, as it does inside a range, and
175
+ # one among later versions does not.
176
+ # : (Array[untyped]) -> untyped
177
+ def self.earliest_version: (Array[untyped]) -> untyped
178
+
124
179
  # : (Array[untyped]) -> Array[untyped]?
125
180
  def self.ambiguous_pair: (Array[untyped]) -> Array[untyped]?
126
181
 
@@ -132,13 +187,6 @@ module PaperTrailDiff
132
187
  # : (untyped) -> untyped
133
188
  def self.version_table: (untyped) -> untyped
134
189
 
135
- # Versions sharing a timestamp, whether or not their ids order them. PT-AT
136
- # indexes association membership per version but resolves it by timestamp,
137
- # so association state cannot be told apart across such a pair even when the
138
- # scalar sequence is perfectly recoverable.
139
- # : (Array[untyped]) -> Array[untyped]?
140
- def self.tied_timestamp_pair: (Array[untyped]) -> Array[untyped]?
141
-
142
190
  # Whether a model records history at all.
143
191
  #
144
192
  # PaperTrail defines `paper_trail` on every ActiveRecord model, so asking
@@ -150,6 +198,38 @@ module PaperTrailDiff
150
198
  # : (untyped) -> bool
151
199
  def self.versioned?: (untyped) -> bool
152
200
 
201
+ # Whether two values are one, as a diff reads them: `==`, but a NaN is the
202
+ # same as a NaN, as PostgreSQL stores and compares it, though Ruby has
203
+ # NaN unequal to everything. A value a serialized attribute holds can be
204
+ # of any class, so `==` must hold both ways, which Active Support's
205
+ # Time == String does not, and a Float is not the Integer it equals: each
206
+ # is written differently, so the change is real. Hashes and arrays are
207
+ # compared by their members.
208
+ # : (untyped, untyped) -> bool
209
+ def self.same?: (untyped, untyped) -> bool
210
+
211
+ # A key the right side lacks reads as a value nothing else is.
212
+ # : (Hash[untyped, untyped], untyped) -> bool
213
+ def self.same_hash?: (Hash[untyped, untyped], untyped) -> bool
214
+
215
+ # : (Array[untyped], untyped) -> bool
216
+ def self.same_array?: (Array[untyped], untyped) -> bool
217
+
218
+ # A Float or BigDecimal NaN.
219
+ # : (untyped) -> bool
220
+ def self.nan?: (untyped) -> bool
221
+
222
+ # An option that is a switch takes only true or false, so a truthy value
223
+ # given by mistake, such as a string, is not read as one.
224
+ # : (Symbol, untyped) -> void
225
+ def self.boolean!: (Symbol, untyped) -> void
226
+
227
+ # Why a versioned model's history holds no states, or nil. PaperTrail
228
+ # can keep versions in a table without an `object` column, and every
229
+ # state is rebuilt from that column.
230
+ # : (untyped) -> String?
231
+ def self.stateless_reason: (untyped) -> String?
232
+
153
233
  # `versions.item_id` is often a string column -- PaperTrail's setup for UUID
154
234
  # keys -- while the model's own key is an integer. An id read from history
155
235
  # is cast to the key's type, or the same record read once from history and
@@ -17,5 +17,9 @@ module PaperTrailDiff
17
17
  # The model's `time` columns, which a model keeps as it was defined.
18
18
  # : (untyped) -> Array[String]
19
19
  def self.columns: (untyped) -> Array[String]
20
+
21
+ # The model's `datetime` columns, kept the same way.
22
+ # : (untyped) -> Array[String]
23
+ def self.datetime_columns: (untyped) -> Array[String]
20
24
  end
21
25
  end
@@ -9,12 +9,38 @@ module PaperTrailDiff
9
9
  # it runs through every version saved since it began, whatever the clock
10
10
  # that dated them read, as a report through the current state does.
11
11
  class TimeRange
12
+ MICROSECOND_DIGITS: ::Integer
13
+
12
14
  attr_reader begin_time: Time
13
15
 
14
16
  attr_reader end_time: Time?
15
17
 
18
+ # The fractional digits its edges are cut to.
19
+ attr_reader digits: Integer
20
+
21
+ # A window over the versions of `models`, its edges cut to the digits
22
+ # their version tables keep. Active Record cuts a time it binds to the
23
+ # precision of the column it is compared with, so an edge left finer than
24
+ # a table that keeps whole seconds would select versions in SQL by the
25
+ # cut time and in Ruby by the whole one. Tables that differ take the
26
+ # coarsest, so that every check of one window cuts it alike.
27
+ # : (untyped, Array[untyped]) -> TimeRange
28
+ def self.for: (untyped, Array[untyped]) -> TimeRange
29
+
30
+ # The fractional digits a model's version table keeps for `created_at`,
31
+ # or nil for a model without versions. A column without a precision
32
+ # keeps whatever the adapter writes, which is microseconds.
33
+ # : (untyped) -> Integer?
34
+ def self.stored_digits: (untyped) -> Integer?
35
+
36
+ # Checks `report(since:)`, the start of the endless window it reads, as
37
+ # that window will read it, so that a message names `since`. A range
38
+ # there would become the start of another range.
16
39
  # : (untyped) -> void
17
- def initialize: (untyped) -> void
40
+ def self.check_since!: (untyped) -> void
41
+
42
+ # : (untyped, ?digits: Integer) -> void
43
+ def initialize: (untyped, ?digits: Integer) -> void
18
44
 
19
45
  # : () -> bool
20
46
  def exclude_end?: () -> bool
@@ -30,18 +56,27 @@ module PaperTrailDiff
30
56
  # : () -> Range[Time?]
31
57
  def to_range: () -> Range[Time?]
32
58
 
59
+ # The window widened to start at `earliest`, where that is before it:
60
+ # what a window reads when a transaction crosses its start (see
61
+ # PreparedHistoryLoader).
62
+ # : (untyped) -> TimeRange
63
+ def widened: (untyped) -> TimeRange
64
+
33
65
  # The versions after the window; none follows an endless one.
34
66
  # : (untyped) -> untyped
35
67
  def trailing_scope: (untyped) -> untyped
36
68
 
37
- # Each item's earliest version after the range, keyed by item id. One row
38
- # per item comes back from a NOT EXISTS rather than a window function, so
39
- # the query stays portable; a timestamp tie keeps the lower id.
69
+ # Each item's earliest version after the range, keyed by item id. The
70
+ # versions at each item's earliest instant come back from a NOT EXISTS
71
+ # rather than a window function, so the query stays portable. A timestamp
72
+ # tie keeps the lower id when ids order it, and raises when they cannot.
40
73
  # : (untyped) -> Hash[String, untyped]
41
74
  def first_trailing_versions: (untyped) -> Hash[String, untyped]
42
75
 
43
76
  private
44
77
 
78
+ @digits: Integer
79
+
45
80
  @exclude_end: bool
46
81
 
47
82
  # : (untyped, Time) -> untyped
@@ -50,6 +85,11 @@ module PaperTrailDiff
50
85
  # : (untyped, Time) -> untyped
51
86
  def after_end: (untyped, Time) -> untyped
52
87
 
88
+ # Cut to the microsecond, as adapters write a time they bind, or to the
89
+ # fewer digits the versions' column keeps: a finer edge would select
90
+ # versions in SQL by the cut time but in Ruby by the whole one, and a
91
+ # version in the edge's microsecond or second would be in one method's
92
+ # window and not another's.
53
93
  # : (untyped, boundary: Symbol) -> Time
54
94
  def coerce_time: (untyped, boundary: Symbol) -> Time
55
95
 
@@ -59,6 +99,11 @@ module PaperTrailDiff
59
99
  # : (untyped) -> untyped
60
100
  def time_value: (untyped) -> untyped
61
101
 
102
+ # A string must name a real day, which `parse` alone does not demand: it
103
+ # reads '12' as noon today and rolls 30 February into March.
104
+ # : (String) -> untyped
105
+ def parse: (String) -> untyped
106
+
62
107
  # An inclusive date end runs through the day: to the next one's start.
63
108
  # : (Range[untyped]) -> untyped
64
109
  def end_value: (Range[untyped]) -> untyped
@@ -19,6 +19,9 @@ module PaperTrailDiff
19
19
 
20
20
  @version_scope: untyped
21
21
 
22
+ # Two are read, so that a tie for first that ids cannot order raises, as
23
+ # a tie inside the range does, instead of the lower id choosing the state
24
+ # the range ends in.
22
25
  # : (untyped) -> untyped
23
26
  def trailing_version: (untyped) -> untyped
24
27
  end
@@ -3,13 +3,10 @@
3
3
  module PaperTrailDiff
4
4
  # Selects and compares a chronological slice of a record's version history.
5
5
  class TimelineBuilder
6
- # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
7
- def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
6
+ # : (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
7
+ def initialize: (untyped, from: untyped, to: untyped, snapshotter: untyped, ?within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
8
8
 
9
- # : () -> Array[Step]
10
- def build: () -> Array[Step]
11
-
12
- # The window the range covers once its edges have moved to transactions.
9
+ # The window the range covers, as it was asked for.
13
10
  # : () -> TimeRange?
14
11
  def window: () -> TimeRange?
15
12
 
@@ -9,16 +9,19 @@ module PaperTrailDiff
9
9
  # *before* the latest change, so a range ending there silently dropped it.
10
10
  LAST_REMOVED: ::String
11
11
 
12
+ # The one symbol a boundary can be, for a timeline's range and for
13
+ # compare_many's endpoints alike.
14
+ # : (Symbol) -> void
15
+ def self.check_symbol!: (Symbol) -> void
16
+
12
17
  attr_reader from: untyped
13
18
 
14
19
  attr_reader to: untyped
15
20
 
16
21
  attr_reader time_range: TimeRange?
17
22
 
18
- # `traversal` names the requested paths, which decide where a window's
19
- # edges move (see TransactionCut).
20
- # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
21
- def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped, ?traversal: AssociationTraversal?) -> void
23
+ # : (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
24
+ def initialize: (untyped, from: untyped, to: untyped, within: untyped, ?version_scope: untyped, ?plan: RootVersionPlan?, ?live_endpoint: untyped) -> void
22
25
 
23
26
  # A record with no versions has no first boundary to resolve, which
24
27
  # is an empty history rather than a bad request. Both endpoints are
@@ -31,9 +34,25 @@ module PaperTrailDiff
31
34
  # The plan says which pairs of versions become steps, which a filter can
32
35
  # make different from adjacent pairs of the selected versions. A `whole`
33
36
  # plan replays every version in the range; see RootVersionSelection.
37
+ # : () -> bool
38
+ def preselected?: () -> bool
39
+
34
40
  # : (?context_required: bool, ?whole: bool) -> RootVersionPlan
35
41
  def select_plan: (?context_required: bool, ?whole: bool) -> RootVersionPlan
36
42
 
43
+ # The plan over the window widened to start at its `reach`: where the
44
+ # earliest transaction across its start began (see PreparedHistoryLoader).
45
+ # : (untyped, context_required: bool) -> RootVersionPlan
46
+ def reach_plan: (untyped, context_required: bool) -> RootVersionPlan
47
+
48
+ # The plan of what the window reports, from the root versions a `wide`
49
+ # plan replays: those whose transactions end inside the window, bounded
50
+ # by the first that ends after it (see TransactionEnds). The root's own
51
+ # mutations among them are those the wide plan names, which a filter
52
+ # chose.
53
+ # : (RootVersionPlan, TransactionEnds, context_required: bool) -> RootVersionPlan
54
+ def reporting_plan: (RootVersionPlan, TransactionEnds, context_required: bool) -> RootVersionPlan
55
+
37
56
  # : () -> bool
38
57
  def time?: () -> bool
39
58
 
@@ -59,10 +78,13 @@ module PaperTrailDiff
59
78
 
60
79
  @to: untyped
61
80
 
62
- @traversal: AssociationTraversal?
63
-
64
81
  @version_scope: untyped
65
82
 
83
+ # The versions whose transactions end inside the window, and the first
84
+ # whose transaction ends after it.
85
+ # : (Array[untyped], TransactionEnds) -> [Array[untyped], untyped]
86
+ def placed: (Array[untyped], TransactionEnds) -> [ Array[untyped], untyped ]
87
+
66
88
  # : (bool) -> RootVersionPlan
67
89
  def explicit_plan: (bool) -> RootVersionPlan
68
90
 
@@ -78,8 +100,7 @@ module PaperTrailDiff
78
100
  # : () -> untyped
79
101
  def ordered_versions: () -> untyped
80
102
 
81
- # A batch passes each root the window it already moved to transaction
82
- # edges; a single record's window is moved here.
103
+ # A batch passes each root its window as it read it.
83
104
  # : (untyped) -> TimeRange?
84
105
  def build_time_range: (untyped) -> TimeRange?
85
106
 
@@ -6,8 +6,14 @@ module PaperTrailDiff
6
6
  # : (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
7
7
  def initialize: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
8
8
 
9
- # : (untyped, Array[untyped]) -> PreparedTimelineSnapshots
10
- def prepare: (untyped, Array[untyped]) -> PreparedTimelineSnapshots
9
+ # Each root version is reported where it was saved, and the records
10
+ # around it read as they stood before every transaction that had not
11
+ # ended yet (see TransactionEnds). So a window's history is read from
12
+ # where the earliest transaction open at its start began, as a batch
13
+ # reads it: one of them may have saved a record before the window. A
14
+ # whole history begins at the root's first version instead.
15
+ # : (untyped, Array[untyped], ?start_at: untyped) -> PreparedTimelineSnapshots
16
+ def prepare: (untyped, Array[untyped], ?start_at: untyped) -> PreparedTimelineSnapshots
11
17
 
12
18
  @live_snapshotter: untyped
13
19
 
@@ -19,14 +25,21 @@ module PaperTrailDiff
19
25
  # nil create state, is kept for this root only and released with it, and
20
26
  # batch memory does not retain every reconstructed graph.
21
27
  class PreparedTimelineSnapshots
22
- # : (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
23
- def initialize: (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
28
+ # : (PreparedHistory?, TransactionEnds?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
29
+ def initialize: (PreparedHistory?, TransactionEnds?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
24
30
 
25
31
  # A window closing on current state ends at the live record rather than at a
26
32
  # version, which is the one endpoint no version history can reconstruct.
27
33
  # : (untyped) -> RecordSnapshot?
28
34
  def call: (untyped) -> RecordSnapshot?
29
35
 
36
+ private
37
+
38
+ # : (untyped) -> RecordSnapshot?
39
+ def at_version: (untyped) -> RecordSnapshot?
40
+
41
+ @ends: TransactionEnds?
42
+
30
43
  @history: PreparedHistory?
31
44
 
32
45
  @live_snapshotter: untyped
@@ -10,8 +10,9 @@ module PaperTrailDiff
10
10
  # already sorts by the key. Such an order is kept as given, since SQL
11
11
  # Server rejects a column listed twice. So is the order of a relation
12
12
  # grouped by anything but the key: each of its rows is a group, which a
13
- # database sorts only by what it groups or aggregates. A relation answers
14
- # for its model the key and table name read here.
13
+ # database sorts only by what it groups or aggregates; one without an order
14
+ # is refused. A relation answers for its model the key and table name read
15
+ # here.
15
16
  # : (untyped) -> untyped
16
17
  def self.apply: (untyped) -> untyped
17
18
 
@@ -23,9 +24,14 @@ module PaperTrailDiff
23
24
  # : (untyped, untyped) -> bool
24
25
  def self.key?: (untyped, untyped) -> bool
25
26
 
27
+ # A name alone or after a table's, each as it is or in the quotes of any
28
+ # adapter here: "name", `name` or [name].
29
+ QUALIFIED_NAME: ::Regexp
30
+
26
31
  # Whether SQL text names the key, alone or after its table's name. That
27
32
  # also finds a key the text only uses, as in `LENGTH(id)`, which then goes
28
- # without the tie-breaker, but it misses no sort by the key.
33
+ # without the tie-breaker, but it misses no sort by the key. Another
34
+ # table's key, quoted or not, is not this one.
29
35
  # : (String, untyped) -> bool
30
36
  def self.key_in_sql?: (String, untyped) -> bool
31
37
  end