Class: RailsCursorPagination::TimestampCursor

Inherits:
Cursor
  • Object
show all
Defined in:
lib/rails_cursor_pagination/timestamp_cursor.rb

Overview

Cursor class that’s used to uniquely identify a record and serialize and deserialize this cursor so that it can be used for pagination. This class expects the ‘order_field` of the record to be a timestamp and is to be used only when sorting a

Instance Attribute Summary

Attributes inherited from Cursor

#id, #order_field_value

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Cursor

from_record

Constructor Details

#initialize(id:, order_field:, order_field_value:) ⇒ TimestampCursor

Initializes the record. Overrides ‘Cursor`’s initializer making all params mandatory.

Parameters:

  • id (Integer) —

    The ID of the cursor record

  • order_field (Symbol) —

    The column or virtual column for ordering

  • order_field_value (Object) —

    The value that the order_field of the record contains



55
56
57
58
59
 
# File 'lib/rails_cursor_pagination/timestamp_cursor.rb', line 55

def initialize(id:, order_field:, order_field_value:)
  super id: id,
        order_field: order_field,
        order_field_value: order_field_value
end

Class Method Details

.decode(encoded_string:, order_field:) ⇒ RailsCursorPagination::TimestampCursor

Decode the provided encoded cursor. Returns an instance of this ‘RailsCursorPagination::Cursor` class containing both the ID and the ordering field value. The ordering field is expected to be a timestamp and is always decoded in the UTC timezone.

Parameters:

  • encoded_string (String) —

    The encoded cursor

  • order_field (Symbol) —

    The column that is being ordered on. It needs to be a timestamp of a class that responds to ‘#strftime`.

Returns:

Raises:



24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/rails_cursor_pagination/timestamp_cursor.rb', line 24

def decode(encoded_string:, order_field:)
  decoded = JSON.parse(Base64.strict_decode64(encoded_string))

  new(
    id: decoded[1],
    order_field: order_field,
    # Turn the order field value into a `Time` instance in UTC. A Rational
    # number allows us to represent fractions of seconds, including the
    # microseconds. In this way we can preserve the order of items with a
    # microsecond precision.
    # This also allows us to keep the size of the cursor small by using
    # just a number instead of having to pass seconds and the fraction of
    # seconds separately.
    order_field_value: Time.at(decoded[0].to_r / (10**6)).utc
  )
rescue ArgumentError, JSON::ParserError
  raise InvalidCursorError,
        "The given cursor `#{encoded_string}` " \
        'could not be decoded to a timestamp'
end

Instance Method Details

#encode ⇒ String

Encodes the cursor as an array containing the timestamp as microseconds from UNIX epoch and the id of the object

Returns:

  • (String)

Raises:



68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
 
# File 'lib/rails_cursor_pagination/timestamp_cursor.rb', line 68

def encode
  unless @order_field_value.respond_to?(:strftime)
    raise ParameterError,
          "Could not encode #{@order_field} " \
          "with value #{@order_field_value}." \
          'It does not respond to #strftime. Is it a timestamp?'
  end

  Base64.strict_encode64(
    [
      @order_field_value.strftime('%s%6N').to_i,
      @id
    ].to_json
  )
end