rails_cursor_pagination 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 43aad1bc560c58779869951edd254017bd3d15c0909022df0aeecbdc5c48bcef
-  data.tar.gz: 3ea26d6133869375d61644eebda2878dd6ccc65b906cbdc5bfa0294bfecd7a0c
+  metadata.gz: 2410928079b14757601fdbb84b8c516a99070f5eee181ab464beeeeb00f302b6
+  data.tar.gz: 7f7e5a25d3977ad18964d35d0e2715978c57ccfdfe8624d229bd275deeb1b542
 SHA512:
-  metadata.gz: dadfee2340eafb20eb0cd5d2e93f76544386554f7e0bf09935915816af72185a2eec6930270883fdd9870b90270a32677e364811b3914c809ffd38a4a839a296
-  data.tar.gz: ba8d85b9cbc57f546bf234f4d4653df7cfe1181cf78f05581c2f0fc4d6ed2a000d8adf39960346fec2b1074d66ab268b45c733d5c0b7e63d3830a54f12352a54
+  metadata.gz: 349ba3f27691109cc3e374dbc0c8340163b8af0b452f158e806f859b7b88e4f6ba7b88bb9a5b9a3c9080ccf53d00c100ba7e166f4b0aec2e2fa0c300591b7ff5
+  data.tar.gz: 802a9c37b80c59dc52c747d6727afa48650572448294114a1f5b70c6092a72d272beb51eeda50b13d2b009598396688eff4969e1d44f13bfa09f7a2f7097c490

data/CHANGELOG.md

@@ -14,6 +14,18 @@ These are the latest changes on the project's `master` branch that have not yet
   Follow the same format as previous releases by categorizing your feature into "Added", "Changed", "Deprecated", "Removed", "Fixed", or "Security".
 --->
 
+## [0.4.0] - 2023-10-06
+
+### Changed
+- **Breaking change:** Raised minimum required Ruby version to 2.7
+- **Breaking change:** Raised minimum required `activerecord` version to 6.0
+
+### Added
+- Test against Ruby version 3.2
+
+### Fixed
+- **Breaking change:** Ensure timestamp `order_by` fields (like `created_at`) will paginate results by honoring timestamp order down to microsecond resolution on comparison. This was done by changing the cursor logic for timestamp fields, which means that the cursors strings change from version 0.3.0 to 0.4.0 and old cursors cannot be decoded by the new gem version anymore. 
+
 ## [0.3.0] - 2022-07-08
 
 ### Added

data/lib/rails_cursor_pagination/cursor.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'base64'
+
 module RailsCursorPagination
   # Cursor class that's used to uniquely identify a record and serialize and
   # deserialize this cursor so that it can be used for pagination.

data/lib/rails_cursor_pagination/paginator.rb

@@ -365,7 +365,7 @@ module RailsCursorPagination
     # @param record [ActiveRecord] Model instance for which we want the cursor
     # @return [String]
     def cursor_for_record(record)
-      Cursor.from_record(record: record, order_field: @order_field).encode
+      cursor_class.from_record(record: record, order_field: @order_field).encode
     end
 
     # Decode the provided cursor. Either just returns the cursor's ID or in case
@@ -375,7 +375,25 @@ module RailsCursorPagination
     # @return [Integer, Array]
     def decoded_cursor
       memoize(:decoded_cursor) do
-        Cursor.decode(encoded_string: @cursor, order_field: @order_field)
+        cursor_class.decode(encoded_string: @cursor, order_field: @order_field)
+      end
+    end
+
+    # Returns the appropriate class for the cursor based on the SQL type of the
+    # column used for ordering the relation.
+    #
+    # @return [Class<RailsCursorPagination::Cursor>]
+    def cursor_class
+      order_field_type = @relation
+                         .column_for_attribute(@order_field)
+                         .sql_type_metadata
+                         .type
+
+      case order_field_type
+      when :datetime
+        TimestampCursor
+      else
+        Cursor
       end
     end
 

data/lib/rails_cursor_pagination/timestamp_cursor.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module RailsCursorPagination
+  # 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
+  class TimestampCursor < Cursor
+    class << self
+      # 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.
+      #
+      # @param encoded_string [String]
+      #   The encoded cursor
+      # @param order_field [Symbol]
+      #   The column that is being ordered on. It needs to be a timestamp of a
+      #   class that responds to `#strftime`.
+      # @raise [RailsCursorPagination::InvalidCursorError]
+      #   In case the given `encoded_string` cannot be decoded properly
+      # @return [RailsCursorPagination::TimestampCursor]
+      #   Instance of this class with a properly decoded timestamp cursor
+      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
+    end
+
+    # Initializes the record. Overrides `Cursor`'s initializer making all params
+    # mandatory.
+    #
+    # @param id [Integer]
+    #   The ID of the cursor record
+    # @param order_field [Symbol]
+    #   The column or virtual column for ordering
+    # @param order_field_value [Object]
+    #   The value that the +order_field+ of the record contains
+    def initialize(id:, order_field:, order_field_value:)
+      super id: id,
+            order_field: order_field,
+            order_field_value: order_field_value
+    end
+
+    # Encodes the cursor as an array containing the timestamp as microseconds
+    # from UNIX epoch and the id of the object
+    #
+    # @raise [RailsCursorPagination::ParameterError]
+    #   The order field value needs to respond to `#strftime` to use the
+    #   `TimestampCursor` class. Otherwise, a `ParameterError` is raised.
+    # @return [String]
+    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
+  end
+end

data/lib/rails_cursor_pagination/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsCursorPagination
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

data/lib/rails_cursor_pagination.rb

@@ -164,6 +164,8 @@ module RailsCursorPagination
 
   require_relative 'rails_cursor_pagination/cursor'
 
+  require_relative 'rails_cursor_pagination/timestamp_cursor'
+
   class << self
     # Allows to configure this gem. Currently supported configuration values
     # are:

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_cursor_pagination
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Nicolas Fricke
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-07-08 00:00:00.000000000 Z
+date: 2023-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '6.0'
 description: This library is an implementation of cursor pagination for ActiveRecord
   relations. Where a regular limit & offset pagination has issues with items that
   are being deleted from or added to the collection on previous pages, cursor pagination
@@ -42,6 +42,7 @@ files:
 - lib/rails_cursor_pagination/configuration.rb
 - lib/rails_cursor_pagination/cursor.rb
 - lib/rails_cursor_pagination/paginator.rb
+- lib/rails_cursor_pagination/timestamp_cursor.rb
 - lib/rails_cursor_pagination/version.rb
 homepage: https://github.com/xing/rails_cursor_pagination
 licenses:
@@ -59,14 +60,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.2.33
 signing_key:
 specification_version: 4
 summary: Add cursor pagination to your ActiveRecord backed application.