Module: PaperTrail::VersionConcern::ClassMethods

Defined in:
lib/paper_trail/version_concern.rb

Overview

:nodoc:

Instance Method Summary collapse

Instance Method Details

#between(start_time, end_time) ⇒ Object 



52
53
54
55
56
57
 
# File 'lib/paper_trail/version_concern.rb', line 52

def between(start_time, end_time)
  where(
    arel_table[:created_at].gt(start_time).
    and(arel_table[:created_at].lt(end_time))
  ).order(timestamp_sort_order)
end

#creates ⇒ Object 



36
37
38
 
# File 'lib/paper_trail/version_concern.rb', line 36

def creates
  where event: "create"
end

#destroys ⇒ Object 



44
45
46
 
# File 'lib/paper_trail/version_concern.rb', line 44

def destroys
  where event: "destroy"
end

#not_creates ⇒ Object 



48
49
50
 
# File 'lib/paper_trail/version_concern.rb', line 48

def not_creates
  where.not(event: "create")
end

#object_changes_col_is_json? ⇒ Boolean

Returns whether the ‘object_changes` column is using the `json` type supported by PostgreSQL.

Returns:

  • (Boolean) 


179
180
181
 
# File 'lib/paper_trail/version_concern.rb', line 179

def object_changes_col_is_json?
  %i[json jsonb].include?(columns_hash["object_changes"].try(:type))
end

#object_col_is_json? ⇒ Boolean

Returns whether the ‘object` column is using the `json` type supported by PostgreSQL.

Returns:

  • (Boolean) 


173
174
175
 
# File 'lib/paper_trail/version_concern.rb', line 173

def object_col_is_json?
  %i[json jsonb].include?(columns_hash["object"].type)
end

#preceding(obj, timestamp_arg = false) ⇒ Object

Returns versions before ‘obj`.

rubocop:disable Style/OptionalBooleanParameter

Parameters:

  • obj —

    • a ‘Version` or a timestamp

  • timestamp_arg (defaults to: false) —

    • boolean - When true, ‘obj` is a timestamp.

    Default: false.

Returns:

  • ‘ActiveRecord::Relation`



191
192
193
194
195
196
197
 
# File 'lib/paper_trail/version_concern.rb', line 191

def preceding(obj, timestamp_arg = false)
  if timestamp_arg != true && primary_key_is_int?
    preceding_by_id(obj)
  else
    preceding_by_timestamp(obj)
  end
end

#primary_key_is_int? ⇒ Boolean

Returns:

  • (Boolean) 


165
166
167
168
169
 
# File 'lib/paper_trail/version_concern.rb', line 165

def primary_key_is_int?
  @primary_key_is_int ||= columns_hash[primary_key].type == :integer
rescue StandardError # TODO: Rescue something more specific
  true
end

#subsequent(obj, timestamp_arg = false) ⇒ Object

Returns versions after ‘obj`.

rubocop:disable Style/OptionalBooleanParameter

Parameters:

  • obj —

    • a ‘Version` or a timestamp

  • timestamp_arg (defaults to: false) —

    • boolean - When true, ‘obj` is a timestamp.

    Default: false.

Returns:

  • ‘ActiveRecord::Relation`



208
209
210
211
212
213
214
 
# File 'lib/paper_trail/version_concern.rb', line 208

def subsequent(obj, timestamp_arg = false)
  if timestamp_arg != true && primary_key_is_int?
    subsequent_by_id(obj)
  else
    subsequent_by_timestamp(obj)
  end
end

#timestamp_sort_order(direction = "asc") ⇒ Object

Defaults to using the primary key as the secondary sort order if possible.



61
62
63
64
65
 
# File 'lib/paper_trail/version_concern.rb', line 61

def timestamp_sort_order(direction = "asc")
  [arel_table[:created_at].send(direction.downcase)].tap do |array|
    array << arel_table[primary_key].send(direction.downcase) if primary_key_is_int?
  end
end

#updates ⇒ Object 



40
41
42
 
# File 'lib/paper_trail/version_concern.rb', line 40

def updates
  where event: "update"
end

#where_attribute_changes(attribute) ⇒ Object

Given an attribute like ‘“name”`, query the `versions.object_changes` column for any changes that modified the provided attribute.



71
72
73
74
75
76
77
 
# File 'lib/paper_trail/version_concern.rb', line 71

def where_attribute_changes(attribute)
  unless attribute.is_a?(String) || attribute.is_a?(Symbol)
    raise ArgumentError, "expected to receive a String or Symbol"
  end

  Queries::Versions::WhereAttributeChanges.new(self, attribute).execute
end

#where_object(args = {}) ⇒ Object

Given a hash of attributes like ‘name: ’Joan’‘, query the `versions.objects` column.

“‘ SELECT “versions”.* FROM “versions” WHERE (“versions”.“object” LIKE ’% name: Joan %‘) “`

This is useful for finding versions where a given attribute had a given value. Imagine, in the example above, that Joan had changed her name and we wanted to find the versions before that change.

Based on the data type of the ‘object` column, the appropriate SQL operator is used. For example, a text column will use `like`, and a jsonb column will use `@>`.

Raises:

  • (ArgumentError) 


99
100
101
102
 
# File 'lib/paper_trail/version_concern.rb', line 99

def where_object(args = {})
  raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
  Queries::Versions::WhereObject.new(self, args).execute
end

#where_object_changes(args = {}) ⇒ Object

Given a hash of attributes like ‘name: ’Joan’‘, query the `versions.objects_changes` column.

“‘ SELECT “versions”.* FROM “versions” WHERE .. (“versions”.“object_changes” LIKE ’% name:

  • Joan

%‘ OR “versions”.“object_changes” LIKE ’% name: -%

  • Joan

%‘) “`

This is useful for finding versions immediately before and after a given attribute had a given value. Imagine, in the example above, that someone changed their name to Joan and we wanted to find the versions immediately before and after that change.

Based on the data type of the ‘object` column, the appropriate SQL operator is used. For example, a text column will use `like`, and a jsonb column will use `@>`.

Raises:

  • (ArgumentError) 


130
131
132
133
 
# File 'lib/paper_trail/version_concern.rb', line 130

def where_object_changes(args = {})
  raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
  Queries::Versions::WhereObjectChanges.new(self, args).execute
end

#where_object_changes_from(args = {}) ⇒ Object

Given a hash of attributes like ‘name: ’Joan’‘, query the `versions.objects_changes` column for changes where the version changed from the hash of attributes to other values.

This is useful for finding versions where the attribute started with a known value and changed to something else. This is in comparison to ‘where_object_changes` which will find both the changes before and after.

Raises:

  • (ArgumentError) 


145
146
147
148
 
# File 'lib/paper_trail/version_concern.rb', line 145

def where_object_changes_from(args = {})
  raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
  Queries::Versions::WhereObjectChangesFrom.new(self, args).execute
end

#where_object_changes_to(args = {}) ⇒ Object

Given a hash of attributes like ‘name: ’Joan’‘, query the `versions.objects_changes` column for changes where the version changed to the hash of attributes from other values.

This is useful for finding versions where the attribute started with an unknown value and changed to a known value. This is in comparison to ‘where_object_changes` which will find both the changes before and after.

Raises:

  • (ArgumentError) 


160
161
162
163
 
# File 'lib/paper_trail/version_concern.rb', line 160

def where_object_changes_to(args = {})
  raise ArgumentError, "expected to receive a Hash" unless args.is_a?(Hash)
  Queries::Versions::WhereObjectChangesTo.new(self, args).execute
end

#with_item_keys(item_type, item_id) ⇒ Object 



32
33
34
 
# File 'lib/paper_trail/version_concern.rb', line 32

def with_item_keys(item_type, item_id)
  where item_type: item_type, item_id: item_id
end