paper_trail_diff 0.14.0 → 0.16.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 (150) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +501 -0
  3. data/QUICKSTART.md +21 -4
  4. data/README.md +59 -56
  5. data/docs/architecture.md +32 -11
  6. data/docs/performance.md +125 -391
  7. data/docs/reference.md +470 -117
  8. data/docs/testing.md +83 -7
  9. data/lib/paper_trail_diff/activity_boundary.rb +83 -26
  10. data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
  11. data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
  12. data/lib/paper_trail_diff/activity_event.rb +41 -10
  13. data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
  14. data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
  15. data/lib/paper_trail_diff/activity_history.rb +34 -9
  16. data/lib/paper_trail_diff/activity_range.rb +18 -3
  17. data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
  18. data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
  19. data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
  20. data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
  21. data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
  22. data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
  23. data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
  24. data/lib/paper_trail_diff/activity_view.rb +69 -0
  25. data/lib/paper_trail_diff/analysis.rb +37 -6
  26. data/lib/paper_trail_diff/analysis_batch.rb +25 -31
  27. data/lib/paper_trail_diff/approximate_paths.rb +48 -0
  28. data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
  29. data/lib/paper_trail_diff/association_discovery.rb +9 -1
  30. data/lib/paper_trail_diff/association_key.rb +56 -0
  31. data/lib/paper_trail_diff/association_traversal.rb +13 -4
  32. data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
  33. data/lib/paper_trail_diff/batch_preload.rb +53 -0
  34. data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
  35. data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
  36. data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
  37. data/lib/paper_trail_diff/change_row.rb +133 -0
  38. data/lib/paper_trail_diff/collection_comparator.rb +5 -32
  39. data/lib/paper_trail_diff/configuration.rb +35 -12
  40. data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
  41. data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
  42. data/lib/paper_trail_diff/deprecation.rb +61 -0
  43. data/lib/paper_trail_diff/diagnostics.rb +86 -99
  44. data/lib/paper_trail_diff/endpoint.rb +26 -3
  45. data/lib/paper_trail_diff/errors.rb +3 -1
  46. data/lib/paper_trail_diff/fallback_paths.rb +38 -0
  47. data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
  48. data/lib/paper_trail_diff/historical_filter.rb +19 -10
  49. data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
  50. data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
  51. data/lib/paper_trail_diff/nested_comparator.rb +19 -18
  52. data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
  53. data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
  54. data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
  55. data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
  56. data/lib/paper_trail_diff/prepared_history.rb +15 -1
  57. data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
  58. data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
  59. data/lib/paper_trail_diff/read_snapshot.rb +77 -0
  60. data/lib/paper_trail_diff/root_version_selection.rb +4 -2
  61. data/lib/paper_trail_diff/scope_condition.rb +157 -32
  62. data/lib/paper_trail_diff/scope_ranking.rb +23 -14
  63. data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
  64. data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
  65. data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
  66. data/lib/paper_trail_diff/snapshot.rb +16 -1
  67. data/lib/paper_trail_diff/support.rb +29 -2
  68. data/lib/paper_trail_diff/time_range.rb +39 -16
  69. data/lib/paper_trail_diff/timeline_builder.rb +13 -7
  70. data/lib/paper_trail_diff/timeline_range.rb +9 -1
  71. data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
  72. data/lib/paper_trail_diff/transaction_cut.rb +240 -0
  73. data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
  74. data/lib/paper_trail_diff/version.rb +1 -1
  75. data/lib/paper_trail_diff/version_boundary.rb +41 -10
  76. data/lib/paper_trail_diff/version_query.rb +34 -10
  77. data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
  78. data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
  79. data/lib/paper_trail_diff/version_table.rb +60 -0
  80. data/lib/paper_trail_diff.rb +101 -57
  81. data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
  82. data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
  83. data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
  84. data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
  85. data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
  86. data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
  87. data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
  88. data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
  89. data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
  90. data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
  91. data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
  92. data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
  93. data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
  94. data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
  95. data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
  96. data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
  97. data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
  98. data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
  99. data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
  100. data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
  101. data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
  102. data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
  103. data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
  104. data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
  105. data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
  106. data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
  107. data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
  108. data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
  109. data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
  110. data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
  111. data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
  112. data/sig/generated/paper_trail_diff/errors.rbs +3 -1
  113. data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
  114. data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
  115. data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
  116. data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
  117. data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
  118. data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
  119. data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
  120. data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
  121. data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
  122. data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
  123. data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
  124. data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
  125. data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
  126. data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
  127. data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
  128. data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
  129. data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
  130. data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
  131. data/sig/generated/paper_trail_diff/support.rbs +15 -0
  132. data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
  133. data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
  134. data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
  135. data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
  136. data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
  137. data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
  138. data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
  139. data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
  140. data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
  141. data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
  142. data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
  143. data/sig/generated/paper_trail_diff.rbs +29 -26
  144. metadata +49 -11
  145. data/lib/paper_trail_diff/activity_grouping.rb +0 -38
  146. data/lib/paper_trail_diff/batch_safety.rb +0 -63
  147. data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
  148. data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
  149. data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
  150. data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
@@ -4,10 +4,10 @@
4
4
  module PaperTrailDiff
5
5
  # Selects both populations and checks their shared ceiling before analysis.
6
6
  class ScopedAnalysisBuilder
7
- #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?) -> void
7
+ #: (untyped, limit: Integer?, within: untyped, historical_filter: untyped, max_filter_versions: Integer, include_deleted: bool, analyzer: untyped, deleted_analyzer: untyped, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
8
8
  def initialize( # rubocop:disable Metrics/ParameterLists
9
9
  scope, limit:, within:, historical_filter:, max_filter_versions:, include_deleted:,
10
- analyzer:, deleted_analyzer:, activity_tree: nil
10
+ analyzer:, deleted_analyzer:, activity_tree: nil, version_scope: nil
11
11
  )
12
12
  raise ConfigurationError, 'limit: is required when selecting roots by scope' if limit.nil?
13
13
  unless [true, false].include?(include_deleted)
@@ -17,10 +17,11 @@ module PaperTrailDiff
17
17
  @selection = ScopedRootSelection.new(
18
18
  scope, limit: limit, time_range: within.nil? ? nil : TimeRange.new(within),
19
19
  historical_filter: historical_filter, max_filter_versions: max_filter_versions,
20
- activity_tree: activity_tree
20
+ activity_tree: activity_tree, version_scope: version_scope
21
21
  )
22
- @limit = limit
22
+ @deleted_filter = deleted_filter(scope, include_deleted)
23
23
  @include_deleted = include_deleted
24
+ @limit = limit
24
25
  @analyzer = analyzer
25
26
  @deleted_analyzer = deleted_analyzer
26
27
  end
@@ -28,20 +29,37 @@ module PaperTrailDiff
28
29
  #: () -> ScopedAnalysis
29
30
  def call
30
31
  selection = @selection.call
31
- if @include_deleted && selection.records.length + selection.unreachable.length > @limit
32
+ unreachable = @deleted_filter&.call(selection.unreachable) || selection.unreachable
33
+ return analysis(selection, unreachable, {}) unless @include_deleted
34
+
35
+ if selection.records.length + unreachable.length > @limit
32
36
  raise BatchLimitExceededError, 'include_deleted: live and missing roots exceed limit:'
33
37
  end
34
38
 
35
- ScopedAnalysis.new(
36
- analyses: @analyzer.call(selection.records), roots: selection.records,
37
- unreachable: selection.unreachable,
38
- deleted: @include_deleted ? @deleted_analyzer.call(selection.unreachable) : {}
39
- )
39
+ analysis(selection, unreachable, @deleted_analyzer.call(unreachable))
40
+ end
41
+
42
+ private
43
+
44
+ # Without the option, the deleted roots are still tested when the
45
+ # relation can be read, so that another selection's are not listed.
46
+ #: (untyped, bool) -> DeletedRootFilter?
47
+ def deleted_filter(scope, include_deleted)
48
+ return DeletedRootFilter.new(scope.all) if include_deleted
49
+
50
+ DeletedRootFilter.readable(scope.all)
51
+ end
52
+
53
+ #: (ScopedRootSelection::Result, Array[Array[String]], Hash[Array[String], Analysis?]) -> ScopedAnalysis
54
+ def analysis(selection, unreachable, deleted)
55
+ ScopedAnalysis.new(analyses: @analyzer.call(selection.records), roots: selection.records,
56
+ unreachable: unreachable, deleted: deleted)
40
57
  end
41
58
 
42
59
  # @rbs @selection: ScopedRootSelection
43
- # @rbs @limit: Integer
60
+ # @rbs @deleted_filter: DeletedRootFilter?
44
61
  # @rbs @include_deleted: bool
62
+ # @rbs @limit: Integer
45
63
  # @rbs @analyzer: untyped
46
64
  # @rbs @deleted_analyzer: untyped
47
65
  end
@@ -45,13 +45,16 @@ module PaperTrailDiff
45
45
 
46
46
  # `activity_tree` names the association paths whose changes also select a
47
47
  # root, as an activity analysis reports them. Without one, only a root's
48
- # own versions select it.
49
- #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?) -> void
48
+ # own versions select it. `version_scope` narrows which of those count,
49
+ # as it narrows which are reported.
50
+ #: (untyped, time_range: TimeRange?, limit: Integer, ?historical_filter: untyped, ?max_filter_versions: Integer, ?activity_tree: AssociationTree?, ?version_scope: untyped) -> void
50
51
  def initialize(scope, time_range:, limit:, historical_filter: nil, # rubocop:disable Metrics/ParameterLists
51
- max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil)
52
+ max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT, activity_tree: nil,
53
+ version_scope: nil)
52
54
  @scope = normalize_scope(scope)
53
55
  reject_unversioned!
54
56
  @time_range = time_range
57
+ @version_scope = VersionScopeFilter.validated(version_scope)
55
58
  @limit = validate_limit(limit)
56
59
  @related = if activity_tree
57
60
  AssociationActivitySelection.new(model, tree: activity_tree,
@@ -80,6 +83,7 @@ module PaperTrailDiff
80
83
  # @rbs @limit: Integer
81
84
  # @rbs @historical_filter: untyped
82
85
  # @rbs @related: AssociationActivitySelection?
86
+ # @rbs @version_scope: untyped
83
87
 
84
88
  # Leaves the candidate set in the database. Plucking every root changed in
85
89
  # the window would cost memory and a statement proportional to all activity
@@ -106,14 +110,22 @@ module PaperTrailDiff
106
110
  matching if matching.length == related.length
107
111
  end
108
112
 
113
+ # Which candidates still have a row is asked without the relation's
114
+ # conditions, so that "filtered out" and "no longer exists" stay
115
+ # separable. A filter then reads the history of the relation's records
116
+ # only, whose order and page choose among those that match, and of the
117
+ # deleted ones, which no relation can test. Those it lists, as without a
118
+ # filter, but does not count toward `limit:`.
109
119
  #: (Array[String]) -> Result
110
120
  def plucked_selection(candidates)
111
- candidates = @historical_filter.call(candidates) if @historical_filter
112
- live = live_ids(candidates)
113
- Result.new(
114
- records: selected_records([live]),
115
- unreachable: (candidates - live).sort.map { |id| identity(id) }.freeze
116
- )
121
+ live = ids_in(base_class.unscoped, candidates)
122
+ missing = candidates - live
123
+ if (filter = @historical_filter)
124
+ live = filter.call(ids_in(@scope.except(:order, :limit, :offset), live).uniq)
125
+ missing = filter.call(missing, counted: false)
126
+ end
127
+ Result.new(records: selected_records([live]),
128
+ unreachable: missing.sort.map { |id| identity(id) }.freeze)
117
129
  end
118
130
 
119
131
  # Comparing the two columns in SQL needs them to share a type: PostgreSQL
@@ -142,11 +154,14 @@ module PaperTrailDiff
142
154
  window_versions.where.not(item_id: base_class.unscoped).distinct.pluck(:item_id).map(&:to_s)
143
155
  end
144
156
 
157
+ # Only the versions `version_scope` keeps select a root: one whose versions
158
+ # in the window it drops would have nothing to report.
145
159
  #: () -> untyped
146
160
  def window_versions
147
- relation = version_class.where(item_type: item_type)
161
+ relation = VersionQuery.for_model(model)
148
162
  range = @time_range
149
- range ? range.scope(relation) : relation
163
+ relation = range.scope(relation) if range
164
+ @version_scope ? @version_scope.call(relation) : relation
150
165
  end
151
166
 
152
167
  # Accepts a model class as readily as a relation: `Article` and
@@ -185,12 +200,10 @@ module PaperTrailDiff
185
200
  window_versions.distinct.pluck(:item_id).map(&:to_s)
186
201
  end
187
202
 
188
- # Which of those candidates still have a row, asked without the relation's
189
- # conditions so that "filtered out" and "no longer exists" stay separable.
190
- #: (Array[String]) -> Array[String]
191
- def live_ids(candidates)
203
+ #: (untyped, Array[String]) -> Array[String]
204
+ def ids_in(relation, candidates)
192
205
  candidates.each_slice(PAGE_SIZE).flat_map do |slice|
193
- base_class.unscoped.where(primary_key => slice).pluck(primary_key).map(&:to_s)
206
+ relation.where(primary_key => slice).pluck(primary_key).map(&:to_s)
194
207
  end
195
208
  end
196
209
 
@@ -102,7 +102,7 @@ module PaperTrailDiff
102
102
  end
103
103
 
104
104
  @kind = kind
105
- @records = records.frozen? ? records : records.dup.freeze
105
+ @records = ordered(records)
106
106
  @identity_index_cache = identity_index_cache || IdentityIndexCache.new
107
107
  @transition = transition
108
108
  @serial = SERIALS.next_serial
@@ -124,6 +124,21 @@ module PaperTrailDiff
124
124
  )
125
125
  end
126
126
 
127
+ # Collections are documented in record type, then ID, order wherever they
128
+ # were read from. Most arrive sorted, so they are checked before sorting.
129
+ #: (Array[RecordSnapshot]) -> Array[RecordSnapshot]
130
+ def ordered(records)
131
+ keys = records.map { |record| Support.sortable_identity(record.type, record.id) }
132
+ return records.sort_by.with_index { |_, index| keys.fetch(index) }.freeze unless sorted?(keys)
133
+
134
+ records.frozen? ? records : records.dup.freeze
135
+ end
136
+
137
+ #: (Array[Array[untyped]]) -> bool
138
+ def sorted?(keys)
139
+ keys.each_cons(2).all? { |left, right| (left <=> right).to_i <= 0 }
140
+ end
141
+
127
142
  #: (AssociationSnapshot) -> CollectionTransition?
128
143
  def transition_from(association)
129
144
  @transition if @transition&.from?(association)
@@ -44,6 +44,20 @@ module PaperTrailDiff
44
44
  end
45
45
  end
46
46
 
47
+ # Records sort by type first so that mixed id types stay comparable, then
48
+ # naturally within one type. Ordering by the printed form instead would put
49
+ # id 10 before id 2, which is deterministic but reads as unsorted wherever a
50
+ # result is rendered.
51
+ #: (untyped, untyped) -> Array[untyped]
52
+ def sortable_identity(type, id)
53
+ key = case id
54
+ when Numeric then [0, id]
55
+ when String, Symbol then [1, id.to_s]
56
+ else [2, id.inspect]
57
+ end
58
+ [type.to_s, key]
59
+ end
60
+
47
61
  #: (untyped) -> Array[untyped]
48
62
  def chronological_version_key(version)
49
63
  version_key(version.created_at, version.id)
@@ -70,11 +84,24 @@ module PaperTrailDiff
70
84
  #: (Array[untyped]) -> Array[untyped]?
71
85
  def ambiguous_pair(sorted)
72
86
  sorted.each_cons(2).find do |left, right|
73
- left.created_at == right.created_at &&
74
- !(sequential_id?(left.id) && sequential_id?(right.id))
87
+ left.created_at == right.created_at && !orderable_tie?(left, right)
75
88
  end
76
89
  end
77
90
 
91
+ # Ids order versions saved in one instant only when they count up in one
92
+ # table. Two version tables count separately, so ids there say nothing.
93
+ #: (untyped, untyped) -> bool
94
+ def orderable_tie?(left, right)
95
+ version_table(left) == version_table(right) &&
96
+ sequential_id?(left.id) && sequential_id?(right.id)
97
+ end
98
+
99
+ #: (untyped) -> untyped
100
+ def version_table(version)
101
+ version.class.respond_to?(:table_name) ? version.class.table_name : version.class.name
102
+ end
103
+ private_class_method :version_table
104
+
78
105
  # Versions sharing a timestamp, whether or not their ids order them. PT-AT
79
106
  # indexes association membership per version but resolves it by timestamp,
80
107
  # so association state cannot be told apart across such a pair even when the
@@ -3,6 +3,10 @@
3
3
 
4
4
  module PaperTrailDiff
5
5
  # Validates and applies a finite wall-clock range without loading model state.
6
+ #
7
+ # A Date is a whole day and a String a local time, both in Time.zone, as
8
+ # Rails reads them, or in UTC without one: never the server's own zone. An
9
+ # inclusive Date end runs through that day.
6
10
  class TimeRange
7
11
  attr_reader :begin_time #: Time
8
12
  attr_reader :end_time #: Time
@@ -14,8 +18,8 @@ module PaperTrailDiff
14
18
  end
15
19
 
16
20
  @begin_time = coerce_time(value.begin, boundary: :begin)
17
- @end_time = coerce_time(value.end, boundary: :end)
18
- @exclude_end = value.exclude_end?
21
+ @exclude_end = value.exclude_end? || calendar_date?(value.end)
22
+ @end_time = coerce_time(end_value(value), boundary: :end)
19
23
  validate_order!
20
24
  freeze
21
25
  end
@@ -35,7 +39,13 @@ module PaperTrailDiff
35
39
 
36
40
  #: (untyped) -> untyped
37
41
  def scope(relation)
38
- relation.where(created_at: query_range)
42
+ relation.where(created_at: to_range)
43
+ end
44
+
45
+ # The window as a Ruby range, its end included or left out as given.
46
+ #: () -> Range[Time]
47
+ def to_range
48
+ exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
39
49
  end
40
50
 
41
51
  #: (untyped) -> untyped
@@ -67,11 +77,6 @@ module PaperTrailDiff
67
77
  exclude_end? ? column.gteq(end_time) : column.gt(end_time)
68
78
  end
69
79
 
70
- #: () -> Range[Time]
71
- def query_range
72
- exclude_end? ? (begin_time...end_time) : (begin_time..end_time)
73
- end
74
-
75
80
  #: (untyped, boundary: Symbol) -> Time
76
81
  def coerce_time(value, boundary:)
77
82
  time_value(value).getutc.freeze
@@ -79,16 +84,34 @@ module PaperTrailDiff
79
84
  raise InvalidTimeRangeError, "`within` #{boundary} must be time-like"
80
85
  end
81
86
 
82
- # Active Support 8.0 and older warn, once per process, that `to_time` will
83
- # change on a zoned time, so read zoned values without it. Every branch
84
- # gives the same instant, so no spec (and no mutation) can tell them apart.
85
- # mutant:disable
86
- #: (untyped) -> Time
87
+ # Anything else names its instant, and `getutc` reads it without
88
+ # `to_time`, which Active Support 8.0 and older warn will change on a
89
+ # zoned time, and without changing the caller's own value as `utc` does.
90
+ #: (untyped) -> untyped
87
91
  def time_value(value)
88
- return value if value.is_a?(Time)
92
+ return zone.parse(value) || raise(ArgumentError) if value.is_a?(String)
93
+ return zone.local(value.year, value.month, value.day) if calendar_date?(value)
94
+
95
+ value
96
+ end
97
+
98
+ # An inclusive date end runs through the day: to the next one's start.
99
+ #: (Range[untyped]) -> untyped
100
+ def end_value(range)
101
+ last = range.end
102
+ calendar_date?(last) && !range.exclude_end? ? last.next_day : last
103
+ end
104
+
105
+ # A DateTime is a Date too, but names its instant.
106
+ #: (untyped) -> bool
107
+ def calendar_date?(value)
108
+ value.instance_of?(Date)
109
+ end
89
110
 
90
- utc = value.utc if value.respond_to?(:utc)
91
- utc.is_a?(Time) ? utc : value.to_time
111
+ #: () -> untyped
112
+ def zone
113
+ time = Time #: untyped
114
+ time.zone || time.find_zone!('UTC')
92
115
  end
93
116
 
94
117
  #: () -> void
@@ -24,6 +24,12 @@ module PaperTrailDiff
24
24
  steps
25
25
  end
26
26
 
27
+ # The window the range covers once its edges have moved to transactions.
28
+ #: () -> TimeRange?
29
+ def window
30
+ @range.time_range
31
+ end
32
+
27
33
  #: () -> Analysis
28
34
  def analyze
29
35
  steps, first_snapshot, last_snapshot = compare_history(selected_versions)
@@ -46,21 +52,21 @@ module PaperTrailDiff
46
52
  return empty_history if plan.empty?
47
53
 
48
54
  versions = plan.versions
49
- @snapshotter.prepare(@record, versions) if @snapshotter.respond_to?(:prepare)
50
- steps = build_steps(plan)
51
- final = plan.closes_on_destroy ? nil : @snapshotter.call(plan.final_endpoint)
52
- [steps, @snapshotter.call(versions.first), final]
55
+ snapshots = @snapshotter.prepare(@record, versions)
56
+ steps = build_steps(plan, snapshots)
57
+ final = plan.closes_on_destroy ? nil : snapshots.call(plan.final_endpoint)
58
+ [steps, snapshots.call(versions.first), final]
53
59
  end
54
60
 
55
- #: (RootVersionPlan) -> Array[Step]
56
- def build_steps(plan)
61
+ #: (RootVersionPlan, untyped) -> Array[Step]
62
+ def build_steps(plan, snapshots)
57
63
  captured_at = Time.now.utc if plan.closing_record
58
64
  plan.steps.map do |from_endpoint, to_endpoint|
59
65
  Step.new(
60
66
  from_version: from_endpoint,
61
67
  to_version: to_endpoint,
62
68
  captured_at: captured_at,
63
- diff: Engine.compare(@snapshotter.call(from_endpoint), @snapshotter.call(to_endpoint))
69
+ diff: Engine.compare(snapshots.call(from_endpoint), snapshots.call(to_endpoint))
64
70
  )
65
71
  end.freeze
66
72
  end
@@ -122,9 +122,17 @@ module PaperTrailDiff
122
122
  VersionQuery.chronological(Endpoint.versions(@record))
123
123
  end
124
124
 
125
+ # A batch passes each root the window it already moved to transaction
126
+ # edges; a single record's window is moved here.
125
127
  #: (untyped) -> TimeRange?
126
128
  def build_time_range(within)
127
- TimeRange.new(within) unless within.nil?
129
+ return if within.nil?
130
+ return within if within.instance_of?(TimeRange)
131
+
132
+ range = TimeRange.new(within)
133
+ return range unless Support.versioned?(@record.class)
134
+
135
+ TransactionCut.windows(@record.class, [@record], range).fetch(@record.id.to_s, range)
128
136
  end
129
137
 
130
138
  #: () -> void
@@ -2,22 +2,35 @@
2
2
  # rbs_inline: enabled
3
3
 
4
4
  module PaperTrailDiff
5
- # Gives TimelineBuilder one-argument access to a range-prepared snapshot store.
5
+ # Prepares the snapshot store for TimelineBuilder, one root at a time.
6
6
  class TimelineSnapshotProvider
7
7
  #: (HistoricalSnapshotStore, live_snapshotter: untyped) -> void
8
8
  def initialize(store, live_snapshotter:)
9
9
  @store = store
10
10
  @live_snapshotter = live_snapshotter
11
- @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
12
11
  end
13
12
 
14
- #: (untyped, Array[untyped]) -> void
13
+ #: (untyped, Array[untyped]) -> PreparedTimelineSnapshots
15
14
  def prepare(record, versions)
16
- # Adjacent steps share endpoints. Keep their immutable snapshots for this
17
- # root only, including nil create states, and release them before the next
18
- # root so batch memory does not retain every reconstructed graph.
19
- @snapshots.clear
20
- @store.prepare(record, versions)
15
+ history = @store.prepare(record, versions)
16
+ PreparedTimelineSnapshots.new(history, store: @store, live_snapshotter: @live_snapshotter)
17
+ end
18
+
19
+ # @rbs @store: HistoricalSnapshotStore
20
+ # @rbs @live_snapshotter: untyped
21
+ end
22
+
23
+ # One root's timeline snapshots, read with the history prepared for it.
24
+ # Adjacent steps share endpoints, so each immutable snapshot, including a
25
+ # nil create state, is kept for this root only and released with it, and
26
+ # batch memory does not retain every reconstructed graph.
27
+ class PreparedTimelineSnapshots
28
+ #: (PreparedHistory?, store: HistoricalSnapshotStore, live_snapshotter: untyped) -> void
29
+ def initialize(history, store:, live_snapshotter:)
30
+ @history = history
31
+ @store = store
32
+ @live_snapshotter = live_snapshotter
33
+ @snapshots = {} #: Hash[Array[untyped], RecordSnapshot?]
21
34
  end
22
35
 
23
36
  # A window closing on current state ends at the live record rather than at a
@@ -28,19 +41,13 @@ module PaperTrailDiff
28
41
  return @snapshots[key] if @snapshots.key?(key)
29
42
 
30
43
  @snapshots[key] = if Endpoint.record?(endpoint)
31
- live_snapshot(endpoint)
44
+ @live_snapshotter.call(endpoint)
32
45
  else
33
- @store.uncached(endpoint, endpoint)
46
+ @store.uncached(endpoint, endpoint, history: @history)
34
47
  end
35
48
  end
36
49
 
37
- private
38
-
39
- #: (untyped) -> RecordSnapshot?
40
- def live_snapshot(record)
41
- @live_snapshotter.call(record)
42
- end
43
-
50
+ # @rbs @history: PreparedHistory?
44
51
  # @rbs @store: HistoricalSnapshotStore
45
52
  # @rbs @live_snapshotter: untyped
46
53
  # @rbs @snapshots: Hash[Array[untyped], RecordSnapshot?]