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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +501 -0
- data/QUICKSTART.md +21 -4
- data/README.md +59 -56
- data/docs/architecture.md +32 -11
- data/docs/performance.md +125 -391
- data/docs/reference.md +470 -117
- data/docs/testing.md +83 -7
- data/lib/paper_trail_diff/activity_boundary.rb +83 -26
- data/lib/paper_trail_diff/activity_child_candidate_loader.rb +2 -1
- data/lib/paper_trail_diff/activity_collection_event_applier.rb +33 -1
- data/lib/paper_trail_diff/activity_event.rb +41 -10
- data/lib/paper_trail_diff/activity_event_route_finder.rb +31 -0
- data/lib/paper_trail_diff/activity_event_snapshot_refresher.rb +12 -1
- data/lib/paper_trail_diff/activity_history.rb +34 -9
- data/lib/paper_trail_diff/activity_range.rb +18 -3
- data/lib/paper_trail_diff/activity_root_snapshot_refresher.rb +43 -25
- data/lib/paper_trail_diff/activity_snapshot_sequence.rb +76 -37
- data/lib/paper_trail_diff/activity_target_candidate_loader.rb +5 -5
- data/lib/paper_trail_diff/activity_timeline_builder.rb +272 -111
- data/lib/paper_trail_diff/activity_transaction_grouper.rb +2 -1
- data/lib/paper_trail_diff/activity_tree_filter.rb +114 -0
- data/lib/paper_trail_diff/activity_version_collector.rb +7 -5
- data/lib/paper_trail_diff/activity_view.rb +69 -0
- data/lib/paper_trail_diff/analysis.rb +37 -6
- data/lib/paper_trail_diff/analysis_batch.rb +25 -31
- data/lib/paper_trail_diff/approximate_paths.rb +48 -0
- data/lib/paper_trail_diff/association_activity_edge.rb +6 -6
- data/lib/paper_trail_diff/association_discovery.rb +9 -1
- data/lib/paper_trail_diff/association_key.rb +56 -0
- data/lib/paper_trail_diff/association_traversal.rb +13 -4
- data/lib/paper_trail_diff/batch_boundary_resolver.rb +3 -4
- data/lib/paper_trail_diff/batch_preload.rb +53 -0
- data/lib/paper_trail_diff/batched_root_analyzer.rb +18 -14
- data/lib/paper_trail_diff/batched_root_versions.rb +38 -14
- data/lib/paper_trail_diff/branch_snapshot_refresher.rb +19 -16
- data/lib/paper_trail_diff/change_row.rb +133 -0
- data/lib/paper_trail_diff/collection_comparator.rb +5 -32
- data/lib/paper_trail_diff/configuration.rb +35 -12
- data/lib/paper_trail_diff/deleted_analysis_batch.rb +23 -19
- data/lib/paper_trail_diff/deleted_root_filter.rb +101 -0
- data/lib/paper_trail_diff/deprecation.rb +61 -0
- data/lib/paper_trail_diff/diagnostics.rb +86 -99
- data/lib/paper_trail_diff/endpoint.rb +26 -3
- data/lib/paper_trail_diff/errors.rb +3 -1
- data/lib/paper_trail_diff/fallback_paths.rb +38 -0
- data/lib/paper_trail_diff/historical_association_reifier.rb +2 -4
- data/lib/paper_trail_diff/historical_filter.rb +19 -10
- data/lib/paper_trail_diff/historical_snapshot_store.rb +57 -67
- data/lib/paper_trail_diff/live_endpoint_batch_loader.rb +1 -35
- data/lib/paper_trail_diff/nested_comparator.rb +19 -18
- data/lib/paper_trail_diff/paper_trail_adapter.rb +198 -166
- data/lib/paper_trail_diff/preloaded_endpoint_batch_loader.rb +13 -1
- data/lib/paper_trail_diff/prepared_activity_index.rb +17 -13
- data/lib/paper_trail_diff/prepared_edge_loader.rb +2 -1
- data/lib/paper_trail_diff/prepared_history.rb +15 -1
- data/lib/paper_trail_diff/prepared_history_loader.rb +2 -3
- data/lib/paper_trail_diff/prepared_record_index.rb +42 -7
- data/lib/paper_trail_diff/read_snapshot.rb +77 -0
- data/lib/paper_trail_diff/root_version_selection.rb +4 -2
- data/lib/paper_trail_diff/scope_condition.rb +157 -32
- data/lib/paper_trail_diff/scope_ranking.rb +23 -14
- data/lib/paper_trail_diff/scoped_analysis.rb +11 -0
- data/lib/paper_trail_diff/scoped_analysis_builder.rb +29 -11
- data/lib/paper_trail_diff/scoped_root_selection.rb +29 -16
- data/lib/paper_trail_diff/snapshot.rb +16 -1
- data/lib/paper_trail_diff/support.rb +29 -2
- data/lib/paper_trail_diff/time_range.rb +39 -16
- data/lib/paper_trail_diff/timeline_builder.rb +13 -7
- data/lib/paper_trail_diff/timeline_range.rb +9 -1
- data/lib/paper_trail_diff/timeline_snapshot_provider.rb +24 -17
- data/lib/paper_trail_diff/transaction_cut.rb +240 -0
- data/lib/paper_trail_diff/traversal_preparer.rb +134 -29
- data/lib/paper_trail_diff/version.rb +1 -1
- data/lib/paper_trail_diff/version_boundary.rb +41 -10
- data/lib/paper_trail_diff/version_query.rb +34 -10
- data/lib/paper_trail_diff/version_scope_filter.rb +9 -10
- data/lib/paper_trail_diff/version_sequence_diagnostics.rb +35 -17
- data/lib/paper_trail_diff/version_table.rb +60 -0
- data/lib/paper_trail_diff.rb +101 -57
- data/sig/generated/paper_trail_diff/activity_boundary.rbs +54 -19
- data/sig/generated/paper_trail_diff/activity_collection_event_applier.rbs +13 -0
- data/sig/generated/paper_trail_diff/activity_event.rbs +25 -4
- data/sig/generated/paper_trail_diff/activity_event_route_finder.rbs +14 -0
- data/sig/generated/paper_trail_diff/activity_event_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/activity_history.rbs +21 -6
- data/sig/generated/paper_trail_diff/activity_range.rbs +9 -2
- data/sig/generated/paper_trail_diff/activity_root_snapshot_refresher.rbs +21 -10
- data/sig/generated/paper_trail_diff/activity_snapshot_sequence.rbs +48 -9
- data/sig/generated/paper_trail_diff/activity_timeline_builder.rbs +138 -30
- data/sig/generated/paper_trail_diff/activity_tree_filter.rbs +73 -0
- data/sig/generated/paper_trail_diff/activity_version_collector.rbs +2 -0
- data/sig/generated/paper_trail_diff/activity_view.rbs +42 -0
- data/sig/generated/paper_trail_diff/analysis.rbs +24 -5
- data/sig/generated/paper_trail_diff/analysis_batch.rbs +8 -15
- data/sig/generated/paper_trail_diff/approximate_paths.rbs +23 -0
- data/sig/generated/paper_trail_diff/association_discovery.rbs +5 -0
- data/sig/generated/paper_trail_diff/association_key.rbs +29 -0
- data/sig/generated/paper_trail_diff/association_traversal.rbs +4 -0
- data/sig/generated/paper_trail_diff/batch_preload.rbs +29 -0
- data/sig/generated/paper_trail_diff/batched_root_analyzer.rbs +13 -10
- data/sig/generated/paper_trail_diff/batched_root_versions.rbs +14 -4
- data/sig/generated/paper_trail_diff/branch_snapshot_refresher.rbs +6 -0
- data/sig/generated/paper_trail_diff/change_row.rbs +86 -0
- data/sig/generated/paper_trail_diff/collection_comparator.rbs +2 -16
- data/sig/generated/paper_trail_diff/configuration.rbs +19 -3
- data/sig/generated/paper_trail_diff/deleted_analysis_batch.rbs +11 -8
- data/sig/generated/paper_trail_diff/deleted_root_filter.rbs +56 -0
- data/sig/generated/paper_trail_diff/deprecation.rbs +35 -0
- data/sig/generated/paper_trail_diff/diagnostics.rbs +37 -30
- data/sig/generated/paper_trail_diff/endpoint.rbs +11 -2
- data/sig/generated/paper_trail_diff/errors.rbs +3 -1
- data/sig/generated/paper_trail_diff/fallback_paths.rbs +22 -0
- data/sig/generated/paper_trail_diff/historical_filter.rbs +12 -2
- data/sig/generated/paper_trail_diff/historical_snapshot_store.rbs +33 -28
- data/sig/generated/paper_trail_diff/live_endpoint_batch_loader.rbs +0 -15
- data/sig/generated/paper_trail_diff/nested_comparator.rbs +10 -7
- data/sig/generated/paper_trail_diff/paper_trail_adapter.rbs +64 -52
- data/sig/generated/paper_trail_diff/preloaded_endpoint_batch_loader.rbs +9 -1
- data/sig/generated/paper_trail_diff/prepared_activity_index.rbs +11 -4
- data/sig/generated/paper_trail_diff/prepared_history.rbs +10 -0
- data/sig/generated/paper_trail_diff/prepared_record_index.rbs +20 -2
- data/sig/generated/paper_trail_diff/read_snapshot.rbs +43 -0
- data/sig/generated/paper_trail_diff/root_version_selection.rbs +2 -0
- data/sig/generated/paper_trail_diff/scope_condition.rbs +81 -15
- data/sig/generated/paper_trail_diff/scope_ranking.rbs +14 -6
- data/sig/generated/paper_trail_diff/scoped_analysis.rbs +6 -0
- data/sig/generated/paper_trail_diff/scoped_analysis_builder.rbs +14 -2
- data/sig/generated/paper_trail_diff/scoped_root_selection.rbs +16 -7
- data/sig/generated/paper_trail_diff/snapshot.rbs +8 -0
- data/sig/generated/paper_trail_diff/support.rbs +15 -0
- data/sig/generated/paper_trail_diff/time_range.rbs +24 -9
- data/sig/generated/paper_trail_diff/timeline_builder.rbs +6 -2
- data/sig/generated/paper_trail_diff/timeline_range.rbs +2 -0
- data/sig/generated/paper_trail_diff/timeline_snapshot_provider.rbs +17 -7
- data/sig/generated/paper_trail_diff/transaction_cut.rbs +126 -0
- data/sig/generated/paper_trail_diff/traversal_preparer.rbs +66 -8
- data/sig/generated/paper_trail_diff/version_boundary.rbs +22 -3
- data/sig/generated/paper_trail_diff/version_query.rbs +18 -2
- data/sig/generated/paper_trail_diff/version_scope_filter.rbs +4 -5
- data/sig/generated/paper_trail_diff/version_sequence_diagnostics.rbs +19 -9
- data/sig/generated/paper_trail_diff/version_table.rbs +30 -0
- data/sig/generated/paper_trail_diff.rbs +29 -26
- metadata +49 -11
- data/lib/paper_trail_diff/activity_grouping.rb +0 -38
- data/lib/paper_trail_diff/batch_safety.rb +0 -63
- data/lib/paper_trail_diff/time_activity_timeline_builder.rb +0 -223
- data/sig/generated/paper_trail_diff/activity_grouping.rbs +0 -22
- data/sig/generated/paper_trail_diff/batch_safety.rbs +0 -30
- data/sig/generated/paper_trail_diff/time_activity_timeline_builder.rbs +0 -92
|
@@ -4,21 +4,24 @@
|
|
|
4
4
|
module PaperTrailDiff
|
|
5
5
|
# Checks the recorded sequence itself, before any question of association
|
|
6
6
|
# setup: whether the versions can be ordered at all, and whether timestamps
|
|
7
|
-
# they share hide changes
|
|
7
|
+
# they share hide changes from a path PT-AT reads.
|
|
8
8
|
class VersionSequenceDiagnostics
|
|
9
|
-
#: (untyped, untyped, ?
|
|
10
|
-
def initialize(from_version, to_version,
|
|
9
|
+
#: (untyped, untyped, ?fallback_selected: bool) -> void
|
|
10
|
+
def initialize(from_version, to_version, fallback_selected: false)
|
|
11
11
|
@from_version = from_version
|
|
12
12
|
@to_version = to_version
|
|
13
|
-
@
|
|
13
|
+
@fallback_selected = fallback_selected
|
|
14
14
|
end
|
|
15
15
|
|
|
16
|
+
# The read runs in a savepoint, so that a query that fails here leaves a
|
|
17
|
+
# snapshot transaction around it usable: PostgreSQL refuses every later
|
|
18
|
+
# statement of a transaction once one has failed.
|
|
16
19
|
#: () -> Array[DiagnosticIssue]
|
|
17
20
|
def call
|
|
18
|
-
versions = ordered_range_versions
|
|
21
|
+
versions = @from_version.class.transaction(requires_new: true) { ordered_range_versions }
|
|
19
22
|
issues = [] #: Array[DiagnosticIssue?]
|
|
20
23
|
issues << unorderable(versions)
|
|
21
|
-
issues << tied_timestamps(versions) if @
|
|
24
|
+
issues << tied_timestamps(versions) if @fallback_selected
|
|
22
25
|
issues.compact
|
|
23
26
|
rescue StandardError
|
|
24
27
|
[]
|
|
@@ -28,7 +31,7 @@ module PaperTrailDiff
|
|
|
28
31
|
|
|
29
32
|
# @rbs @from_version: untyped
|
|
30
33
|
# @rbs @to_version: untyped
|
|
31
|
-
# @rbs @
|
|
34
|
+
# @rbs @fallback_selected: bool
|
|
32
35
|
|
|
33
36
|
# Ordering falls back to the id when timestamps tie, which only recovers the
|
|
34
37
|
# real sequence for ids that increase with insertion. Reported before a run
|
|
@@ -46,11 +49,12 @@ module PaperTrailDiff
|
|
|
46
49
|
)
|
|
47
50
|
end
|
|
48
51
|
|
|
49
|
-
#
|
|
50
|
-
#
|
|
51
|
-
#
|
|
52
|
-
#
|
|
53
|
-
#
|
|
52
|
+
# Loaded history orders versions that share a timestamp by id, but PT-AT
|
|
53
|
+
# places association changes by timestamp alone, so a path it reads loses
|
|
54
|
+
# any change between such a pair. Unlike an unorderable sequence this is
|
|
55
|
+
# not always wrong: if nothing that path reaches changed between them the
|
|
56
|
+
# result is correct, and the gem cannot tell which it is, because not
|
|
57
|
+
# seeing the change is the symptom. So it warns.
|
|
54
58
|
#: (Array[untyped]) -> DiagnosticIssue?
|
|
55
59
|
def tied_timestamps(versions)
|
|
56
60
|
pair = Support.tied_timestamp_pair(versions)
|
|
@@ -61,22 +65,36 @@ module PaperTrailDiff
|
|
|
61
65
|
severity: :warning,
|
|
62
66
|
code: :tied_version_timestamps,
|
|
63
67
|
message: "versions #{left.id.inspect} and #{right.id.inspect} share the timestamp " \
|
|
64
|
-
"#{left.created_at.inspect},
|
|
65
|
-
'
|
|
68
|
+
"#{left.created_at.inspect}, and an association requested here is read with " \
|
|
69
|
+
'PT-AT, which places association changes by timestamp alone, so a change ' \
|
|
70
|
+
'between them can be missed; record versions at sub-second precision to ' \
|
|
71
|
+
'separate them',
|
|
66
72
|
version_id: left.id
|
|
67
73
|
)
|
|
68
74
|
end
|
|
69
75
|
|
|
70
76
|
#: () -> Array[untyped]
|
|
71
77
|
def ordered_range_versions
|
|
72
|
-
|
|
73
|
-
return [] unless
|
|
78
|
+
range = time_range
|
|
79
|
+
return [] unless range
|
|
74
80
|
|
|
75
81
|
@from_version.class
|
|
76
82
|
.where(item_type: @from_version.item_type, item_id: @from_version.item_id)
|
|
77
|
-
.where(created_at:
|
|
83
|
+
.where(created_at: range)
|
|
78
84
|
.to_a
|
|
79
85
|
.sort_by { |version| Support.chronological_version_key(version) }
|
|
80
86
|
end
|
|
87
|
+
|
|
88
|
+
# Between the two versions, in either order, or from the one version on
|
|
89
|
+
# when the other endpoint is the current record. A version that recorded
|
|
90
|
+
# no time bounds nothing.
|
|
91
|
+
#: () -> Range[untyped]?
|
|
92
|
+
def time_range
|
|
93
|
+
from = @from_version.created_at
|
|
94
|
+
return from && (from..) unless @to_version
|
|
95
|
+
|
|
96
|
+
bounds = [from, @to_version.created_at].compact.sort
|
|
97
|
+
bounds.first..bounds.last if bounds.length == 2
|
|
98
|
+
end
|
|
81
99
|
end
|
|
82
100
|
end
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# frozen_string_literal: true
|
|
2
|
+
# rbs_inline: enabled
|
|
3
|
+
|
|
4
|
+
module PaperTrailDiff
|
|
5
|
+
# PT-AT reads an association's history from its owner's version tables: it
|
|
6
|
+
# looks for a child's versions in the owner's version table, and numbers a
|
|
7
|
+
# transaction by the first version saved in it, in whichever table. A model
|
|
8
|
+
# whose versions, or version associations, live in another table than its
|
|
9
|
+
# owner's would read other records' versions or none, so it is refused.
|
|
10
|
+
module VersionTable
|
|
11
|
+
# Why the association, or a part of a through, cannot be read across
|
|
12
|
+
# version tables.
|
|
13
|
+
#: (untyped) -> String?
|
|
14
|
+
def self.unsupported_reason(reflection)
|
|
15
|
+
part = separate_part(reflection)
|
|
16
|
+
return unless part
|
|
17
|
+
|
|
18
|
+
"#{part.active_record.name}##{part.name} keeps versions in #{tables(part.active_record)} " \
|
|
19
|
+
"but #{part.klass.name} in #{tables(part.klass)}, and association history is read " \
|
|
20
|
+
'from one set of version tables'
|
|
21
|
+
end
|
|
22
|
+
|
|
23
|
+
# The reflection, or the first part of a through, whose ends keep versions
|
|
24
|
+
# in different tables. A polymorphic belongs_to names no single target,
|
|
25
|
+
# and an unversioned target has no history to compare.
|
|
26
|
+
#: (untyped) -> untyped
|
|
27
|
+
def self.separate_part(reflection)
|
|
28
|
+
if reflection.through_reflection?
|
|
29
|
+
return [reflection.through_reflection, reflection.source_reflection].filter_map do |part|
|
|
30
|
+
separate_part(part)
|
|
31
|
+
end.first
|
|
32
|
+
end
|
|
33
|
+
return if reflection.polymorphic?
|
|
34
|
+
|
|
35
|
+
owner = reflection.active_record
|
|
36
|
+
target = reflection.klass
|
|
37
|
+
return unless Support.versioned?(owner) && Support.versioned?(target)
|
|
38
|
+
|
|
39
|
+
reflection unless tables(owner) == tables(target)
|
|
40
|
+
end
|
|
41
|
+
private_class_method :separate_part
|
|
42
|
+
|
|
43
|
+
# PT-AT's version association rows joined to the versions they were saved
|
|
44
|
+
# with. Its `belongs_to :version` names PaperTrail's default class whatever
|
|
45
|
+
# table a model's versions are in, so the join names the table instead.
|
|
46
|
+
#: (untyped, untyped) -> untyped
|
|
47
|
+
def self.joined(associations, versions)
|
|
48
|
+
rows = associations.arel_table
|
|
49
|
+
table = versions.arel_table
|
|
50
|
+
associations.joins(rows.join(table).on(table[:id].eq(rows[:version_id])).join_sources)
|
|
51
|
+
end
|
|
52
|
+
|
|
53
|
+
#: (untyped) -> String
|
|
54
|
+
def self.tables(model)
|
|
55
|
+
history = model.paper_trail
|
|
56
|
+
"#{history.version_class.table_name} and #{history.version_association_class.table_name}"
|
|
57
|
+
end
|
|
58
|
+
private_class_method :tables
|
|
59
|
+
end
|
|
60
|
+
end
|
data/lib/paper_trail_diff.rb
CHANGED
|
@@ -9,14 +9,18 @@ require_relative 'paper_trail_diff/version_query'
|
|
|
9
9
|
require_relative 'paper_trail_diff/stored_time_precision'
|
|
10
10
|
require_relative 'paper_trail_diff/version_boundary'
|
|
11
11
|
require_relative 'paper_trail_diff/instrumentation'
|
|
12
|
+
require_relative 'paper_trail_diff/deprecation'
|
|
12
13
|
require_relative 'paper_trail_diff/errors'
|
|
13
14
|
require_relative 'paper_trail_diff/configuration'
|
|
14
15
|
require_relative 'paper_trail_diff/endpoint'
|
|
15
16
|
require_relative 'paper_trail_diff/recorded_class'
|
|
17
|
+
require_relative 'paper_trail_diff/association_key'
|
|
18
|
+
require_relative 'paper_trail_diff/version_table'
|
|
16
19
|
require_relative 'paper_trail_diff/association_traversal'
|
|
17
20
|
require_relative 'paper_trail_diff/scope_ranking'
|
|
18
21
|
require_relative 'paper_trail_diff/scope_condition'
|
|
19
|
-
require_relative 'paper_trail_diff/
|
|
22
|
+
require_relative 'paper_trail_diff/approximate_paths'
|
|
23
|
+
require_relative 'paper_trail_diff/fallback_paths'
|
|
20
24
|
require_relative 'paper_trail_diff/traversal_preparer'
|
|
21
25
|
require_relative 'paper_trail_diff/association_discovery'
|
|
22
26
|
require_relative 'paper_trail_diff/diagnostics'
|
|
@@ -30,6 +34,7 @@ require_relative 'paper_trail_diff/traversal_emitter'
|
|
|
30
34
|
require_relative 'paper_trail_diff/snapshot_traversal'
|
|
31
35
|
require_relative 'paper_trail_diff/association_diff_traversal'
|
|
32
36
|
require_relative 'paper_trail_diff/traversal'
|
|
37
|
+
require_relative 'paper_trail_diff/change_row'
|
|
33
38
|
require_relative 'paper_trail_diff/collection_comparator'
|
|
34
39
|
require_relative 'paper_trail_diff/nested_comparator'
|
|
35
40
|
require_relative 'paper_trail_diff/engine'
|
|
@@ -46,6 +51,7 @@ require_relative 'paper_trail_diff/prepared_edge_loader'
|
|
|
46
51
|
require_relative 'paper_trail_diff/prepared_history_loader'
|
|
47
52
|
require_relative 'paper_trail_diff/prepared_association_reifier'
|
|
48
53
|
require_relative 'paper_trail_diff/live_association_reader'
|
|
54
|
+
require_relative 'paper_trail_diff/batch_preload'
|
|
49
55
|
require_relative 'paper_trail_diff/live_endpoint_batch_loader'
|
|
50
56
|
require_relative 'paper_trail_diff/preloaded_endpoint_batch_loader'
|
|
51
57
|
require_relative 'paper_trail_diff/live_endpoint_provider'
|
|
@@ -73,7 +79,7 @@ require_relative 'paper_trail_diff/activity_event_snapshot_refresher'
|
|
|
73
79
|
require_relative 'paper_trail_diff/activity_root_snapshot_refresher'
|
|
74
80
|
require_relative 'paper_trail_diff/branch_snapshot_refresher'
|
|
75
81
|
require_relative 'paper_trail_diff/activity_boundary'
|
|
76
|
-
require_relative 'paper_trail_diff/
|
|
82
|
+
require_relative 'paper_trail_diff/activity_view'
|
|
77
83
|
require_relative 'paper_trail_diff/activity_transaction_grouper'
|
|
78
84
|
require_relative 'paper_trail_diff/step'
|
|
79
85
|
require_relative 'paper_trail_diff/analysis'
|
|
@@ -85,11 +91,13 @@ require_relative 'paper_trail_diff/historical_filter'
|
|
|
85
91
|
require_relative 'paper_trail_diff/association_activity_edge'
|
|
86
92
|
require_relative 'paper_trail_diff/association_activity_selection'
|
|
87
93
|
require_relative 'paper_trail_diff/scoped_root_selection'
|
|
94
|
+
require_relative 'paper_trail_diff/deleted_root_filter'
|
|
88
95
|
require_relative 'paper_trail_diff/scoped_analysis_builder'
|
|
89
96
|
require_relative 'paper_trail_diff/batched_root_analyzer'
|
|
90
97
|
require_relative 'paper_trail_diff/version_range'
|
|
91
98
|
require_relative 'paper_trail_diff/version_sequence_diagnostics'
|
|
92
99
|
require_relative 'paper_trail_diff/time_range'
|
|
100
|
+
require_relative 'paper_trail_diff/transaction_cut'
|
|
93
101
|
require_relative 'paper_trail_diff/time_version_range'
|
|
94
102
|
require_relative 'paper_trail_diff/timeline_range'
|
|
95
103
|
require_relative 'paper_trail_diff/timeline_builder'
|
|
@@ -99,9 +107,10 @@ require_relative 'paper_trail_diff/activity_child_candidate_loader'
|
|
|
99
107
|
require_relative 'paper_trail_diff/activity_target_candidate_loader'
|
|
100
108
|
require_relative 'paper_trail_diff/activity_version_collector'
|
|
101
109
|
require_relative 'paper_trail_diff/activity_snapshot_sequence'
|
|
110
|
+
require_relative 'paper_trail_diff/activity_tree_filter'
|
|
102
111
|
require_relative 'paper_trail_diff/activity_history'
|
|
103
|
-
require_relative 'paper_trail_diff/time_activity_timeline_builder'
|
|
104
112
|
require_relative 'paper_trail_diff/activity_timeline_builder'
|
|
113
|
+
require_relative 'paper_trail_diff/read_snapshot'
|
|
105
114
|
require_relative 'paper_trail_diff/paper_trail_adapter'
|
|
106
115
|
|
|
107
116
|
# @rbs!
|
|
@@ -118,10 +127,10 @@ require_relative 'paper_trail_diff/paper_trail_adapter'
|
|
|
118
127
|
# type comparison_input = Hash[String | Symbol, untyped]
|
|
119
128
|
# type comparison_results = Hash[identity, Diff]
|
|
120
129
|
# type report_options = {
|
|
121
|
-
# within: untyped, activity: bool, version_scope: untyped,
|
|
122
|
-
# close_on: Symbol?, snapshots: bool, group: Symbol?
|
|
130
|
+
# within: untyped, activity: bool, version_scope: untyped, view: ActivityView
|
|
123
131
|
# }
|
|
124
132
|
# type ignore_option = Array[String | Symbol] | Hash[String | Symbol, untyped]
|
|
133
|
+
# type association_option = String | Symbol | Array[untyped] | Hash[untyped, untyped]
|
|
125
134
|
# type reference_key = :type | :id | "type" | "id"
|
|
126
135
|
# type traversal_context = :change | :included_state
|
|
127
136
|
# type traversal_state = :before | :after
|
|
@@ -142,43 +151,45 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
142
151
|
|
|
143
152
|
class << self # rubocop:disable Metrics/ClassLength
|
|
144
153
|
# Compares net state between explicit PaperTrail-version or current-record endpoints.
|
|
145
|
-
#: (untyped, untyped, ?associations:
|
|
146
|
-
def compare(
|
|
154
|
+
#: (untyped, untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_approximate: bool) -> Diff
|
|
155
|
+
def compare( # rubocop:disable Metrics/ParameterLists
|
|
147
156
|
from_version,
|
|
148
157
|
to_version,
|
|
149
158
|
associations: [],
|
|
150
159
|
ignore: DEFAULT_IGNORED_ATTRIBUTES,
|
|
151
|
-
reload_live_endpoints:
|
|
160
|
+
reload_live_endpoints: nil,
|
|
161
|
+
allow_approximate: false
|
|
152
162
|
)
|
|
153
163
|
PaperTrailAdapter.new(
|
|
154
164
|
associations: associations,
|
|
155
165
|
ignore: ignore,
|
|
156
|
-
reload_live_endpoints: reload_live_endpoints
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
to_version
|
|
160
|
-
)
|
|
166
|
+
reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
|
|
167
|
+
allow_approximate: allow_approximate
|
|
168
|
+
).compare(from_version, to_version)
|
|
161
169
|
end
|
|
162
170
|
|
|
163
171
|
# Compares many independent endpoint pairs while batching current-record loading.
|
|
164
|
-
#: (Array[comparison_input], ?associations:
|
|
165
|
-
def compare_many(
|
|
172
|
+
#: (Array[comparison_input], ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?allow_expensive: bool?, ?allow_approximate: bool) -> comparison_results
|
|
173
|
+
def compare_many( # rubocop:disable Metrics/ParameterLists
|
|
166
174
|
comparisons,
|
|
167
175
|
associations: [],
|
|
168
176
|
ignore: DEFAULT_IGNORED_ATTRIBUTES,
|
|
169
|
-
reload_live_endpoints:
|
|
170
|
-
allow_expensive:
|
|
177
|
+
reload_live_endpoints: nil,
|
|
178
|
+
allow_expensive: nil,
|
|
179
|
+
allow_approximate: false
|
|
171
180
|
)
|
|
181
|
+
Deprecation.allow_expensive!(allow_expensive)
|
|
172
182
|
PaperTrailAdapter.new(
|
|
173
183
|
associations: associations,
|
|
174
184
|
ignore: ignore,
|
|
175
|
-
reload_live_endpoints: reload_live_endpoints,
|
|
185
|
+
reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
|
|
186
|
+
allow_approximate: allow_approximate
|
|
176
187
|
).compare_many(comparisons)
|
|
177
188
|
end
|
|
178
189
|
|
|
179
190
|
# Compares every adjacent reconstructed state in an inclusive version range,
|
|
180
191
|
# by default the record's whole history through its current state.
|
|
181
|
-
#: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations:
|
|
192
|
+
#: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?close_on: Symbol?, ?allow_approximate: bool) -> Array[Step]
|
|
182
193
|
def timeline( # rubocop:disable Metrics/ParameterLists
|
|
183
194
|
record,
|
|
184
195
|
from: nil,
|
|
@@ -187,23 +198,23 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
187
198
|
associations: [],
|
|
188
199
|
ignore: DEFAULT_IGNORED_ATTRIBUTES,
|
|
189
200
|
version_scope: nil,
|
|
190
|
-
close_on: nil
|
|
201
|
+
close_on: nil,
|
|
202
|
+
allow_approximate: false
|
|
191
203
|
)
|
|
192
|
-
|
|
204
|
+
Deprecation.close_on!(close_on, within)
|
|
205
|
+
PaperTrailAdapter.new(
|
|
206
|
+
associations: associations, ignore: ignore, allow_approximate: allow_approximate
|
|
207
|
+
).timeline(
|
|
193
208
|
record,
|
|
194
209
|
from: from,
|
|
195
210
|
to: to,
|
|
196
211
|
within: within,
|
|
197
|
-
version_scope: version_scope
|
|
198
|
-
close_on: close_on
|
|
212
|
+
version_scope: version_scope
|
|
199
213
|
)
|
|
200
214
|
end
|
|
201
215
|
|
|
202
216
|
# Compares adjacent root and selected-descendant activity boundaries.
|
|
203
|
-
|
|
204
|
-
# record: an explicit `to:` record, the default range, or a window with no
|
|
205
|
-
# later version.
|
|
206
|
-
#: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: Array[String | Symbol], ?ignore: ignore_option, ?reload_live_endpoints: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?) -> Array[ActivityStep]
|
|
217
|
+
#: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?reload_live_endpoints: bool?, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Array[ActivityStep]
|
|
207
218
|
def activity_timeline( # rubocop:disable Metrics/ParameterLists
|
|
208
219
|
record,
|
|
209
220
|
from: nil,
|
|
@@ -211,30 +222,32 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
211
222
|
within: nil,
|
|
212
223
|
associations: [],
|
|
213
224
|
ignore: DEFAULT_IGNORED_ATTRIBUTES,
|
|
214
|
-
reload_live_endpoints:
|
|
225
|
+
reload_live_endpoints: nil,
|
|
215
226
|
version_scope: nil,
|
|
216
227
|
close_on: nil,
|
|
217
228
|
snapshots: false,
|
|
218
|
-
group: nil
|
|
229
|
+
group: nil,
|
|
230
|
+
recorded_changes: false,
|
|
231
|
+
allow_approximate: false
|
|
219
232
|
)
|
|
233
|
+
Deprecation.close_on!(close_on, within)
|
|
220
234
|
PaperTrailAdapter.new(
|
|
221
|
-
associations: associations,
|
|
222
|
-
|
|
223
|
-
|
|
235
|
+
associations: associations, ignore: ignore,
|
|
236
|
+
reload_live_endpoints: Deprecation.reload_live_endpoints!(reload_live_endpoints),
|
|
237
|
+
recorded_changes: recorded_changes, allow_approximate: allow_approximate
|
|
224
238
|
).activity_timeline(
|
|
225
239
|
record,
|
|
226
240
|
from: from,
|
|
227
241
|
to: to,
|
|
228
242
|
within: within,
|
|
229
243
|
version_scope: version_scope,
|
|
230
|
-
close_on: close_on,
|
|
231
244
|
group: group,
|
|
232
245
|
snapshots: snapshots
|
|
233
246
|
)
|
|
234
247
|
end
|
|
235
248
|
|
|
236
249
|
# Builds an endpoint diff and root-checkpoint timeline while normalizing each version once.
|
|
237
|
-
#: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations:
|
|
250
|
+
#: (untyped, ?from: untyped, ?to: untyped, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?recorded_changes: bool, ?allow_approximate: bool) -> Analysis
|
|
238
251
|
def analyze( # rubocop:disable Metrics/ParameterLists
|
|
239
252
|
record,
|
|
240
253
|
from: nil,
|
|
@@ -246,16 +259,21 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
246
259
|
version_scope: nil,
|
|
247
260
|
close_on: nil,
|
|
248
261
|
snapshots: false,
|
|
249
|
-
group: nil
|
|
262
|
+
group: nil,
|
|
263
|
+
recorded_changes: false,
|
|
264
|
+
allow_approximate: false
|
|
250
265
|
)
|
|
251
|
-
|
|
266
|
+
Deprecation.close_on!(close_on, within)
|
|
267
|
+
PaperTrailAdapter.new(
|
|
268
|
+
associations: associations, ignore: ignore, recorded_changes: recorded_changes,
|
|
269
|
+
allow_approximate: allow_approximate
|
|
270
|
+
).analyze(
|
|
252
271
|
record,
|
|
253
272
|
from: from,
|
|
254
273
|
to: to,
|
|
255
274
|
within: within,
|
|
256
275
|
activity: activity,
|
|
257
276
|
version_scope: version_scope,
|
|
258
|
-
close_on: close_on,
|
|
259
277
|
snapshots: snapshots,
|
|
260
278
|
group: group
|
|
261
279
|
)
|
|
@@ -266,7 +284,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
266
284
|
# returns a frozen Hash keyed by identity. Roots with nothing to report in
|
|
267
285
|
# the window return an empty `Analysis`. To let a relation choose the
|
|
268
286
|
# records, use `analyze_scope`.
|
|
269
|
-
#: (Array[untyped], ?within: untyped, ?associations:
|
|
287
|
+
#: (Array[untyped], ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> Hash[identity, Analysis]
|
|
270
288
|
def analyze_many( # rubocop:disable Metrics/ParameterLists
|
|
271
289
|
records,
|
|
272
290
|
within: nil,
|
|
@@ -277,12 +295,17 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
277
295
|
close_on: nil,
|
|
278
296
|
snapshots: false,
|
|
279
297
|
group: nil,
|
|
280
|
-
allow_expensive:
|
|
298
|
+
allow_expensive: nil,
|
|
299
|
+
recorded_changes: false,
|
|
300
|
+
allow_approximate: false
|
|
281
301
|
)
|
|
302
|
+
Deprecation.close_on!(close_on, within)
|
|
303
|
+
Deprecation.allow_expensive!(allow_expensive)
|
|
282
304
|
PaperTrailAdapter.new(
|
|
283
|
-
associations: associations, ignore: ignore,
|
|
305
|
+
associations: associations, ignore: ignore,
|
|
306
|
+
recorded_changes: recorded_changes, allow_approximate: allow_approximate
|
|
284
307
|
).analyze_many(records, within: within, activity: activity, version_scope: version_scope,
|
|
285
|
-
|
|
308
|
+
snapshots: snapshots, group: group)
|
|
286
309
|
end
|
|
287
310
|
|
|
288
311
|
# Analyzes every root the relation reaches whose history moved inside the
|
|
@@ -311,7 +334,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
311
334
|
# Note also that a relation selects on current state, not on state during
|
|
312
335
|
# the window: `where(status: 'published')` means published *now*, which is a
|
|
313
336
|
# different set from what was published while the window was open.
|
|
314
|
-
#: (untyped, limit: Integer?, ?within: untyped, ?associations:
|
|
337
|
+
#: (untyped, limit: Integer?, ?within: untyped, ?associations: association_option, ?ignore: ignore_option, ?activity: bool, ?version_scope: untyped, ?close_on: Symbol?, ?snapshots: bool, ?group: Symbol?, ?historical_filter: untyped, ?max_filter_versions: Integer, ?include_deleted: bool, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
|
|
315
338
|
def analyze_scope( # rubocop:disable Metrics/ParameterLists
|
|
316
339
|
scope,
|
|
317
340
|
limit:,
|
|
@@ -326,13 +349,18 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
326
349
|
historical_filter: nil,
|
|
327
350
|
max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
|
|
328
351
|
include_deleted: false,
|
|
329
|
-
allow_expensive:
|
|
352
|
+
allow_expensive: nil,
|
|
353
|
+
recorded_changes: false,
|
|
354
|
+
allow_approximate: false
|
|
330
355
|
)
|
|
356
|
+
Deprecation.close_on!(close_on, within)
|
|
357
|
+
Deprecation.allow_expensive!(allow_expensive)
|
|
331
358
|
adapter = PaperTrailAdapter.new(associations: associations, ignore: ignore,
|
|
332
|
-
|
|
359
|
+
recorded_changes: recorded_changes,
|
|
360
|
+
allow_approximate: allow_approximate)
|
|
333
361
|
adapter.analyze_scope(
|
|
334
362
|
scope, limit: limit, within: within, activity: activity,
|
|
335
|
-
version_scope: version_scope,
|
|
363
|
+
version_scope: version_scope, snapshots: snapshots, group: group,
|
|
336
364
|
historical_filter: historical_filter, max_filter_versions: max_filter_versions,
|
|
337
365
|
include_deleted: include_deleted
|
|
338
366
|
)
|
|
@@ -342,21 +370,36 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
342
370
|
# for every root that changed or whose requested associations did.
|
|
343
371
|
# Historical windows remain explicit on analyze_scope; this entry point is
|
|
344
372
|
# deliberately named for a report through now rather than an as-of query.
|
|
345
|
-
#: (untyped, since: untyped, limit: Integer, ?associations:
|
|
373
|
+
#: (untyped, since: untyped, limit: Integer, ?associations: association_option, ?ignore: ignore_option, ?version_scope: untyped, ?snapshots: bool, ?group: Symbol?, ?include_deleted: bool, ?historical_filter: untyped, ?max_filter_versions: Integer, ?allow_expensive: bool?, ?recorded_changes: bool, ?allow_approximate: bool) -> ScopedAnalysis
|
|
346
374
|
def report( # rubocop:disable Metrics/ParameterLists
|
|
347
375
|
scope, since:, limit:, associations: [], ignore: DEFAULT_IGNORED_ATTRIBUTES,
|
|
348
|
-
snapshots: false, group: nil, include_deleted: false,
|
|
349
|
-
max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
|
|
376
|
+
version_scope: nil, snapshots: false, group: nil, include_deleted: false,
|
|
377
|
+
historical_filter: nil, max_filter_versions: HistoricalFilter::DEFAULT_VERSION_LIMIT,
|
|
378
|
+
allow_expensive: nil, recorded_changes: false, allow_approximate: false
|
|
350
379
|
)
|
|
380
|
+
# A range here would become the start of another range.
|
|
381
|
+
if since.nil? || since.is_a?(Range)
|
|
382
|
+
raise InvalidTimeRangeError, '`since` must be a time, date, or string; for a range, ' \
|
|
383
|
+
'pass it as `within:` to analyze_scope'
|
|
384
|
+
end
|
|
385
|
+
|
|
351
386
|
analyze_scope(
|
|
352
387
|
scope,
|
|
353
388
|
within: since..Time.now.utc, limit: limit, associations: associations,
|
|
354
|
-
ignore: ignore, activity: true,
|
|
389
|
+
ignore: ignore, activity: true, version_scope: version_scope, snapshots: snapshots,
|
|
390
|
+
group: group,
|
|
355
391
|
include_deleted: include_deleted, historical_filter: historical_filter,
|
|
356
|
-
max_filter_versions: max_filter_versions, allow_expensive: allow_expensive
|
|
392
|
+
max_filter_versions: max_filter_versions, allow_expensive: allow_expensive,
|
|
393
|
+
recorded_changes: recorded_changes, allow_approximate: allow_approximate
|
|
357
394
|
)
|
|
358
395
|
end
|
|
359
396
|
|
|
397
|
+
# Warns about deprecated options; see Deprecation.
|
|
398
|
+
#: () -> untyped
|
|
399
|
+
def deprecator
|
|
400
|
+
Deprecation.deprecator
|
|
401
|
+
end
|
|
402
|
+
|
|
360
403
|
# Returns the association macros this release can normalize.
|
|
361
404
|
#: () -> Array[Symbol]
|
|
362
405
|
def supported_association_macros
|
|
@@ -369,10 +412,13 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
369
412
|
AssociationDiscovery.new(model_or_record, max_depth: max_depth).call
|
|
370
413
|
end
|
|
371
414
|
|
|
372
|
-
# Reports known reconstruction hazards without mutating application state
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
415
|
+
# Reports known reconstruction hazards without mutating application state,
|
|
416
|
+
# for the endpoints `compare` takes: two versions, or a version and the
|
|
417
|
+
# current record. Every reason `compare` would refuse them is an error.
|
|
418
|
+
#: (untyped, untyped, ?associations: association_option, ?allow_approximate: bool) -> DiagnosticReport
|
|
419
|
+
def diagnose(from, to, associations: [], allow_approximate: false)
|
|
420
|
+
HistoryDiagnostics.new(from, to, associations: associations,
|
|
421
|
+
allow_approximate: allow_approximate).call
|
|
376
422
|
end
|
|
377
423
|
|
|
378
424
|
# Looks inside an attribute the database stores whole, such as a JSON or
|
|
@@ -404,9 +450,7 @@ module PaperTrailDiff # rubocop:disable Metrics/ModuleLength
|
|
|
404
450
|
|
|
405
451
|
# Reads what PaperTrail recorded with one version: its `object_changes`,
|
|
406
452
|
# typed by the version's model, as `{ "title" => <from "Draft" to "Published"> }`.
|
|
407
|
-
#
|
|
408
|
-
# versions = PaperTrail::Version.where(id: steps.map { _1.source_boundary.version_id })
|
|
409
|
-
# versions.to_h { [_1.id, PaperTrailDiff.recorded_changes(_1)] }
|
|
453
|
+
# Activity methods read it for every step source with `recorded_changes: true`.
|
|
410
454
|
#
|
|
411
455
|
# A step's diff compares the states before and after an event, so it also
|
|
412
456
|
# includes anything saved without a version in between; this does not.
|
|
@@ -24,26 +24,49 @@ module PaperTrailDiff
|
|
|
24
24
|
# report one save as one step rather than as its parts.
|
|
25
25
|
attr_reader transaction_id: untyped
|
|
26
26
|
|
|
27
|
-
|
|
28
|
-
def self.from_version: (untyped) -> ActivityBoundary
|
|
27
|
+
@recorded_changes: untyped
|
|
29
28
|
|
|
30
|
-
#
|
|
31
|
-
|
|
29
|
+
# Stands for recorded changes nobody asked to read, which differs from a
|
|
30
|
+
# version that recorded nothing (nil).
|
|
31
|
+
NOT_READ: untyped
|
|
32
|
+
|
|
33
|
+
NOT_READ_MESSAGE: ::String
|
|
34
|
+
|
|
35
|
+
# `recorded:` names the attributes to leave out of the version's recorded
|
|
36
|
+
# changes, or is nil when they were not asked for. Reading them decodes
|
|
37
|
+
# `object_changes`, which a caller who does not want them should not pay.
|
|
38
|
+
# : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
|
|
39
|
+
def self.from_version: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
|
|
40
|
+
|
|
41
|
+
# The current record has no version, so it recorded nothing.
|
|
42
|
+
# : (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
|
|
43
|
+
def self.current: (untyped, captured_at: untyped, ?recorded: Array[String]?) -> ActivityBoundary
|
|
32
44
|
|
|
33
45
|
# The state a `destroy` version leaves behind. A version records the state
|
|
34
46
|
# before its own event, so the boundary built from a destroy version still
|
|
35
47
|
# holds the record; this one is the absence that follows it.
|
|
36
|
-
# : (untyped) -> ActivityBoundary
|
|
37
|
-
def self.destroyed: (untyped) -> ActivityBoundary
|
|
38
|
-
|
|
39
|
-
#
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
#
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
48
|
+
# : (untyped, ?recorded: Array[String]?) -> ActivityBoundary
|
|
49
|
+
def self.destroyed: (untyped, ?recorded: Array[String]?) -> ActivityBoundary
|
|
50
|
+
|
|
51
|
+
# : (untyped, Array[String]?) -> untyped
|
|
52
|
+
private def self.recorded_changes: (untyped, Array[String]?) -> untyped
|
|
53
|
+
|
|
54
|
+
# `recorded_changes:` takes what `PaperTrailDiff.recorded_changes` returns
|
|
55
|
+
# for the version; leave it out when they were not read.
|
|
56
|
+
# : (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
|
|
57
|
+
def initialize: (kind: Symbol, version_id: untyped, item_type: untyped, item_id: untyped, recorded_at: untyped, ?event: untyped, ?whodunnit: untyped, ?transaction_id: untyped, ?recorded_changes: untyped) -> void
|
|
58
|
+
|
|
59
|
+
# What PaperTrail recorded with this boundary's version, as
|
|
60
|
+
# `PaperTrailDiff.recorded_changes` returns it: nil when nothing was
|
|
61
|
+
# recorded, and always nil for the current record, which has no version.
|
|
62
|
+
# Raises unless the timeline was built with `recorded_changes: true`, so a
|
|
63
|
+
# forgotten option cannot pass for a version that recorded nothing.
|
|
64
|
+
# : () -> Hash[String, ValueChange]?
|
|
65
|
+
def recorded_changes: () -> Hash[String, ValueChange]?
|
|
66
|
+
|
|
67
|
+
# Whether this boundary's recorded changes were read.
|
|
68
|
+
# : () -> bool
|
|
69
|
+
def recorded_changes?: () -> bool
|
|
47
70
|
|
|
48
71
|
# : () -> bool
|
|
49
72
|
def version?: () -> bool
|
|
@@ -75,14 +98,20 @@ module PaperTrailDiff
|
|
|
75
98
|
|
|
76
99
|
attr_reader to_snapshot: RecordSnapshot?
|
|
77
100
|
|
|
101
|
+
# The events whose changes this step reports, in the order they happened.
|
|
102
|
+
# That is `source_boundary` alone, unless the step is a transaction group,
|
|
103
|
+
# which holds every event in it: an attribution that names only the first
|
|
104
|
+
# would credit the rest of the save to whoever opened it.
|
|
105
|
+
attr_reader sources: Array[ActivityBoundary]
|
|
106
|
+
|
|
78
107
|
# Compares two reconstructed states and keeps them only when asked, which is
|
|
79
108
|
# every caller's shape: the diff always comes from the pair, the pair itself
|
|
80
109
|
# is retained on request.
|
|
81
|
-
# : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
|
|
82
|
-
def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool) -> ActivityStep
|
|
110
|
+
# : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
|
|
111
|
+
def self.between: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, from_snapshot: RecordSnapshot?, to_snapshot: RecordSnapshot?, retain: bool, ?sources: Array[ActivityBoundary]?) -> ActivityStep
|
|
83
112
|
|
|
84
|
-
# : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
|
|
85
|
-
def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?) -> void
|
|
113
|
+
# : (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
|
|
114
|
+
def initialize: (from_boundary: ActivityBoundary, to_boundary: ActivityBoundary, diff: Diff, ?from_snapshot: RecordSnapshot?, ?to_snapshot: RecordSnapshot?, ?sources: Array[ActivityBoundary]?) -> void
|
|
86
115
|
|
|
87
116
|
# : () -> bool
|
|
88
117
|
def empty?: () -> bool
|
|
@@ -92,6 +121,12 @@ module PaperTrailDiff
|
|
|
92
121
|
# : () -> ActivityBoundary
|
|
93
122
|
def source_boundary: () -> ActivityBoundary
|
|
94
123
|
|
|
124
|
+
# The diff as flat rows, each attributed to `source_boundary`.
|
|
125
|
+
# : () -> Array[ChangeRow]
|
|
126
|
+
def change_rows: () -> Array[ChangeRow]
|
|
127
|
+
|
|
128
|
+
# `metadata: true` also lists `sources`, since who made a change is
|
|
129
|
+
# metadata as much as the source boundary's own author is.
|
|
95
130
|
# : (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
|
|
96
131
|
def to_h: (?metadata: bool, ?snapshots: bool) -> Hash[Symbol, untyped]
|
|
97
132
|
end
|