rails_cursor_pagination 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92ff9fc0d88af01bbcee5b6bc749790494b476fe425492f799a1ebd0e4a35cf7
-  data.tar.gz: 421e730132cc775c717e10bfb05309a98419d6096166f24db631390cfb4792cb
+  metadata.gz: 43aad1bc560c58779869951edd254017bd3d15c0909022df0aeecbdc5c48bcef
+  data.tar.gz: 3ea26d6133869375d61644eebda2878dd6ccc65b906cbdc5bfa0294bfecd7a0c
 SHA512:
-  metadata.gz: 653cbdf05a63e16adab8f991dcf9fa90b0799424174c8b8838795f2f8cccdb89cd823e7a5708e485a8113e2af3ea6362c8a2696bfdac783ac30b8108795df841
-  data.tar.gz: 6307cfb673d4d18ed4dff27efdc5de2f042cfeb09332d23cb7813ff7bf79ed761b219b7486330ff924dcbe624325b41a75a71955312dcd30992a84299ba5193c
+  metadata.gz: dadfee2340eafb20eb0cd5d2e93f76544386554f7e0bf09935915816af72185a2eec6930270883fdd9870b90270a32677e364811b3914c809ffd38a4a839a296
+  data.tar.gz: ba8d85b9cbc57f546bf234f4d4653df7cfe1181cf78f05581c2f0fc4d6ed2a000d8adf39960346fec2b1074d66ab268b45c733d5c0b7e63d3830a54f12352a54

data/CHANGELOG.md

@@ -14,6 +14,21 @@ 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.3.0] - 2022-07-08
+
+### Added
+- Add a `limit` param to paginator that can be used instead either `first` or `last`
+- Add a `max_page_size` to the configuration, allowing to set a global limit to the page size (non overridable): Default `nil`
+- Support explicitly requesting all columns via `.select(*)` without re-including the requested column
+
+### Removed
+- **Breaking change:** Drop support for Ruby 2.5 (EOL 2021-03-31)
+
+### Changed
+- **Breaking change:** Remove nesting of `ParameterError` and `InvalidCursorError` errors, they are now directly nested under the main gem module. So they're now `RailsCursorPagination::ParameterError` and `RailsCursorPagination::InvalidCursorError`.
+- Refactor paginator cursor interactions into exposed `RailsCursorPagination::Cursor` class
+- Require multi-factor-authentication to publish the gem on Rubygems
+
 ## [0.2.0] - 2021-04-19
 
 ### Changed

data/README.md

@@ -120,6 +120,21 @@ RailsCursorPagination::Paginator
   .fetch
 ```
 
+Alternatively, you can use the `limit` column with either `after` or `before`.
+This will behave like either `first` or `last` respectively and fetch X records.
+
+```ruby
+RailsCursorPagination::Paginator
+  .new(posts, limit: 2, after: 'MTA=')
+  .fetch
+```
+
+```ruby
+RailsCursorPagination::Paginator
+  .new(posts, limit: 2, before: 'MTA=')
+  .fetch
+```
+
 ### Ordering
 
 As said, this gem ignores any previous ordering added to the passed relation.
@@ -216,7 +231,15 @@ end
 ```
 
 This would set the default page size to 50.
-                       
+
+You can also select a global `max_page_size` to prevent a client from requesting too large a page.
+
+```ruby
+RailsCursorPagination.configure do |config|
+  config.max_page_size = 100
+end
+```
+
 ### The passed relation
 
 The relation passed to the `RailsCursorPagination::Paginator` needs to be an instance of an `ActiveRecord::Relation`.
@@ -404,6 +427,20 @@ You can also run `bin/console` for an interactive prompt that will allow you to
 To install this gem onto your local machine, run `bundle exec rake install`.
 To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+## Supported environments
+
+This gem should run in any project that uses:
+* Ruby
+* `ActiveRecord`
+* Postgres or MySQL
+
+We aim to support all versions that are still actively maintained and extend support until one year past the version's EOL.
+While we think it's important to stay up-to-date with versions and update as soon as an EOL is reached, we know that this is not always immediately possible.
+This way, we hope to strike a balance between being usable by most projects without forcing them to upgrade, but also keeping the supported version combinations manageable.
+
+This project is tested against different permutations of Ruby versions and DB versions, both Postgres and MySQL.
+Please check the [test automation file under `./.github/workflows/test.yml`](.github/workflows/test.yml) to see all officially supported combinations.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/xing/rails_cursor_pagination.

data/lib/rails_cursor_pagination/configuration.rb

@@ -10,12 +10,13 @@ module RailsCursorPagination
   #
   #    RailsCursorPagination.configure do |config|
   #      config.default_page_size = 42
+  #      config.max_page_size = 100
   #    end
   #
   class Configuration
     include Singleton
 
-    attr_accessor :default_page_size
+    attr_accessor :default_page_size, :max_page_size
 
     # Ensure the default values are set on first initialization
     def initialize
@@ -25,6 +26,7 @@ module RailsCursorPagination
     # Reset all values to their defaults
     def reset!
       @default_page_size = 10
+      @max_page_size = nil
     end
   end
 end

data/lib/rails_cursor_pagination/cursor.rb

@@ -0,0 +1,108 @@
+# 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.
+  class Cursor
+    attr_reader :id, :order_field_value
+
+    class << self
+      # Generate a cursor for the given record and ordering field. The cursor
+      # encodes all the data required to then paginate based on it with the
+      # given ordering field.
+      #
+      # @param record [ActiveRecord]
+      #   Model instance for which we want the cursor
+      # @param order_field [Symbol]
+      #   Column or virtual column of the record that the relation is ordered by
+      # @return [Cursor]
+      def from_record(record:, order_field: :id)
+        new(id: record.id, order_field: order_field,
+            order_field_value: record[order_field])
+      end
+
+      # Decode the provided encoded cursor. Returns an instance of this
+      # +RailsCursorPagination::Cursor+ class containing either just the
+      # cursor's ID or in case of pagination on any other field, containing
+      # both the ID and the ordering field value.
+      #
+      # @param encoded_string [String]
+      #   The encoded cursor
+      # @param order_field [Symbol]
+      #   Optional. The column that is being ordered on in case it's not the ID
+      #   column
+      # @return [RailsCursorPagination::Cursor]
+      def decode(encoded_string:, order_field: :id)
+        decoded = JSON.parse(Base64.strict_decode64(encoded_string))
+        if order_field == :id
+          if decoded.is_a?(Array)
+            raise InvalidCursorError,
+                  "The given cursor `#{encoded_string}` was decoded as " \
+                  "`#{decoded}` but could not be parsed"
+          end
+          new(id: decoded, order_field: :id)
+        else
+          unless decoded.is_a?(Array) && decoded.size == 2
+            raise InvalidCursorError,
+                  "The given cursor `#{encoded_string}` was decoded as " \
+                  "`#{decoded}` but could not be parsed"
+          end
+          new(id: decoded[1], order_field: order_field,
+              order_field_value: decoded[0])
+        end
+      rescue ArgumentError, JSON::ParserError
+        raise InvalidCursorError,
+              "The given cursor `#{encoded_string}` could not be decoded"
+      end
+    end
+
+    # Initializes the record
+    #
+    # @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]
+    #   Optional. The value that the +order_field+ of the record contains in
+    #   case that the order field is not the ID
+    def initialize(id:, order_field: :id, order_field_value: nil)
+      @id = id
+      @order_field = order_field
+      @order_field_value = order_field_value
+
+      return if !custom_order_field? || !order_field_value.nil?
+
+      raise ParameterError, 'The `order_field` was set to ' \
+                            "`#{@order_field.inspect}` but " \
+                            'no `order_field_value` was set'
+    end
+
+    # Generate an encoded string for this cursor. The cursor encodes all the
+    # data required to then paginate based on it with the given ordering field.
+    #
+    # If we only order by ID, the cursor doesn't need to include any other data.
+    # But if we order by any other field, the cursor needs to include both the
+    # value from this other field as well as the records ID to resolve the order
+    # of duplicates in the non-ID field.
+    #
+    # @return [String]
+    def encode
+      unencoded_cursor =
+        if custom_order_field?
+          [@order_field_value, @id]
+        else
+          @id
+        end
+      Base64.strict_encode64(unencoded_cursor.to_json)
+    end
+
+    private
+
+    # Returns true when the order has been overridden from the default (ID)
+    #
+    # @return [Boolean]
+    def custom_order_field?
+      @order_field != :id
+    end
+  end
+end

data/lib/rails_cursor_pagination/paginator.rb

@@ -11,18 +11,13 @@ module RailsCursorPagination
   #       .fetch
   #
   class Paginator
-    # Generic error that gets raised when invalid parameters are passed to the
-    # Paginator initializer
-    class ParameterError < Error; end
-
-    # Error that gets raised if a cursor given as `before` or `after` parameter
-    # cannot be properly parsed
-    class InvalidCursorError < ParameterError; end
-
     # Create a new instance of the `RailsCursorPagination::Paginator`
     #
     # @param relation [ActiveRecord::Relation]
     #   Relation that will be paginated.
+    # @param limit [Integer, nil]
+    #   Number of records to return in pagination. Can be combined with either
+    #   `after` or `before` as an alternative to `first` or `last`.
     # @param first [Integer, nil]
     #   Number of records to return in a forward pagination. Can be combined
     #   with `after`.
@@ -43,14 +38,15 @@ module RailsCursorPagination
     # @param order [Symbol, nil]
     #   Ordering to apply, either `:asc` or `:desc`. Defaults to `:asc`.
     #
-    # @raise [RailsCursorPagination::Paginator::ParameterError]
+    # @raise [RailsCursorPagination::ParameterError]
     #   If any parameter is not valid
-    def initialize(relation, first: nil, after: nil, last: nil, before: nil,
-                   order_by: nil, order: nil)
+    def initialize(relation, limit: nil, first: nil, after: nil, last: nil,
+                   before: nil, order_by: nil, order: nil)
       order_by ||= :id
       order ||= :asc
 
-      ensure_valid_params!(relation, first, after, last, before, order)
+      ensure_valid_params_values!(relation, order, limit, first, last)
+      ensure_valid_params_combinations!(first, last, limit, before, after)
 
       @order_field = order_by
       @order_direction = order
@@ -62,8 +58,14 @@ module RailsCursorPagination
       @page_size =
         first ||
         last ||
+        limit ||
         RailsCursorPagination::Configuration.instance.default_page_size
 
+      if Configuration.instance.max_page_size &&
+         Configuration.instance.max_page_size < @page_size
+        @page_size = Configuration.instance.max_page_size
+      end
+
       @memos = {}
     end
 
@@ -83,50 +85,79 @@ module RailsCursorPagination
 
     private
 
-    # Ensure that the parameters of this service are valid. Otherwise raise
-    # a `RailsCursorPagination::Paginator::ParameterError`.
+    # Ensure that the parameters of this service have valid values, otherwise
+    # raise a `RailsCursorPagination::ParameterError`.
     #
     # @param relation [ActiveRecord::Relation]
     #   Relation that will be paginated.
+    # @param order [Symbol]
+    #   Must be :asc or :desc
+    # @param limit [Integer, nil]
+    #   Optional, must be positive
     # @param first [Integer, nil]
-    #   Optional, must be positive, cannot be combined with `last`
-    # @param after [String, nil]
-    #   Optional, cannot be combined with `before`
+    #   Optional, must be positive
     # @param last [Integer, nil]
-    #   Optional, must be positive, requires `before`, cannot be combined
-    #   with `first`
-    # @param before [String, nil]
-    #   Optional, cannot be combined with `after`
-    # @param order [Symbol]
-    #   Optional, must be :asc or :desc
+    #   Optional, must be positive
+    #   with `first` or `limit`
     #
-    # @raise [RailsCursorPagination::Paginator::ParameterError]
+    # @raise [RailsCursorPagination::ParameterError]
     #   If any parameter is not valid
-    def ensure_valid_params!(relation, first, after, last, before, order)
+    def ensure_valid_params_values!(relation, order, limit, first, last)
       unless relation.is_a?(ActiveRecord::Relation)
         raise ParameterError,
-              'The first argument must be an ActiveRecord::Relation, but was '\
+              'The first argument must be an ActiveRecord::Relation, but was ' \
               "the #{relation.class} `#{relation.inspect}`"
       end
       unless %i[asc desc].include?(order)
         raise ParameterError,
               "`order` must be either :asc or :desc, but was `#{order}`"
       end
+      if first.present? && first.negative?
+        raise ParameterError, "`first` cannot be negative, but was `#{first}`"
+      end
+      if last.present? && last.negative?
+        raise ParameterError, "`last` cannot be negative, but was `#{last}`"
+      end
+      if limit.present? && limit.negative?
+        raise ParameterError, "`limit` cannot be negative, but was `#{limit}`"
+      end
+
+      true
+    end
+
+    # Ensure that the parameters of this service are combined in a valid way.
+    # Otherwise raise a +RailsCursorPagination::ParameterError+.
+    #
+    # @param limit [Integer, nil]
+    #   Optional, cannot be combined with `last` or `first`
+    # @param first [Integer, nil]
+    #   Optional, cannot be combined with `last` or `limit`
+    # @param after [String, nil]
+    #   Optional, cannot be combined with `before`
+    # @param last [Integer, nil]
+    #   Optional, requires `before`, cannot be combined
+    #   with `first` or `limit`
+    # @param before [String, nil]
+    #   Optional, cannot be combined with `after`
+    #
+    # @raise [RailsCursorPagination::ParameterError]
+    #   If parameters are combined in an invalid way
+    def ensure_valid_params_combinations!(first, last, limit, before, after)
       if first.present? && last.present?
         raise ParameterError, '`first` cannot be combined with `last`'
       end
+      if first.present? && limit.present?
+        raise ParameterError, '`limit` cannot be combined with `first`'
+      end
+      if last.present? && limit.present?
+        raise ParameterError, '`limit` cannot be combined with `last`'
+      end
       if before.present? && after.present?
         raise ParameterError, '`before` cannot be combined with `after`'
       end
       if last.present? && before.blank?
         raise ParameterError, '`last` must be combined with `before`'
       end
-      if first.present? && first.negative?
-        raise ParameterError, "`first` cannot be negative, but was `#{first}`"
-      end
-      if last.present? && last.negative?
-        raise ParameterError, "`last` cannot be negative, but was `#{last}`"
-      end
 
       true
     end
@@ -317,9 +348,9 @@ module RailsCursorPagination
     #
     # @return [Integer, String]
     def filter_value
-      return decoded_cursor_id unless custom_order_field?
+      return decoded_cursor.id unless custom_order_field?
 
-      "#{decoded_cursor_field}-#{decoded_cursor_id}"
+      "#{decoded_cursor.order_field_value}-#{decoded_cursor.id}"
     end
 
     # Generate a cursor for the given record and ordering field. The cursor
@@ -334,14 +365,7 @@ module RailsCursorPagination
     # @param record [ActiveRecord] Model instance for which we want the cursor
     # @return [String]
     def cursor_for_record(record)
-      unencoded_cursor =
-        if custom_order_field?
-          [record[@order_field], record.id]
-        else
-          record.id
-        end
-
-      Base64.strict_encode64(unencoded_cursor.to_json)
+      Cursor.from_record(record: record, order_field: @order_field).encode
     end
 
     # Decode the provided cursor. Either just returns the cursor's ID or in case
@@ -350,37 +374,9 @@ module RailsCursorPagination
     #
     # @return [Integer, Array]
     def decoded_cursor
-      memoize(:decoded_cursor) { JSON.parse(Base64.strict_decode64(@cursor)) }
-    rescue ArgumentError, JSON::ParserError
-      raise InvalidCursorError,
-            "The given cursor `#{@cursor.inspect}` could not be decoded"
-    end
-
-    # Return the ID of the cursor's record. In case we use an ordering by ID,
-    # this is all the data the cursor encodes. Otherwise, it's the second
-    # element of the tuple encoded by the cursor.
-    #
-    # @return [Integer]
-    def decoded_cursor_id
-      return decoded_cursor unless decoded_cursor.is_a? Array
-
-      decoded_cursor.last
-    end
-
-    # Return the value of the cursor's record's custom order field. Only exists
-    # if the cursor was generated by a query with a custom order field.
-    # Otherwise the cursor would only encode the ID and not be an array.
-
-    # @raise [InvalidCursorError] in case the cursor is not a tuple
-    # @return [Object]
-    def decoded_cursor_field
-      unless decoded_cursor.is_a? Array
-        raise InvalidCursorError,
-              "The given cursor `#{@cursor}` was decoded as "\
-              "`#{decoded_cursor.inspect}` but could not be parsed"
+      memoize(:decoded_cursor) do
+        Cursor.decode(encoded_string: @cursor, order_field: @order_field)
       end
-
-      decoded_cursor.first
     end
 
     # Ensure that the relation has the ID column and any potential `order_by`
@@ -389,7 +385,8 @@ module RailsCursorPagination
     #
     # @return [ActiveRecord::Relation]
     def relation_with_cursor_fields
-      return @relation if @relation.select_values.blank?
+      return @relation if @relation.select_values.blank? ||
+                          @relation.select_values.include?('*')
 
       relation = @relation
 
@@ -453,15 +450,16 @@ module RailsCursorPagination
 
         unless custom_order_field?
           next sorted_relation.where "#{id_column} #{filter_operator} ?",
-                                     decoded_cursor_id
+                                     decoded_cursor.id
         end
 
         sorted_relation
-          .where("#{@order_field} #{filter_operator} ?", decoded_cursor_field)
+          .where("#{@order_field} #{filter_operator} ?",
+                 decoded_cursor.order_field_value)
           .or(
             sorted_relation
-              .where("#{@order_field} = ?", decoded_cursor_field)
-              .where("#{id_column} #{filter_operator} ?", decoded_cursor_id)
+              .where("#{@order_field} = ?", decoded_cursor.order_field_value)
+              .where("#{id_column} #{filter_operator} ?", decoded_cursor.id)
           )
       end
     end

data/lib/rails_cursor_pagination/version.rb

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

data/lib/rails_cursor_pagination.rb

@@ -148,12 +148,22 @@
 module RailsCursorPagination
   class Error < StandardError; end
 
+  # Generic error that gets raised when invalid parameters are passed to the
+  # pagination
+  class ParameterError < Error; end
+
+  # Error that gets raised if a cursor given as `before` or `after` cannot be
+  # properly parsed
+  class InvalidCursorError < ParameterError; end
+
   require_relative 'rails_cursor_pagination/version'
 
   require_relative 'rails_cursor_pagination/configuration'
 
   require_relative 'rails_cursor_pagination/paginator'
 
+  require_relative 'rails_cursor_pagination/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.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Nicolas Fricke
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-19 00:00:00.000000000 Z
+date: 2022-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -40,6 +40,7 @@ files:
 - README.md
 - lib/rails_cursor_pagination.rb
 - lib/rails_cursor_pagination/configuration.rb
+- lib/rails_cursor_pagination/cursor.rb
 - lib/rails_cursor_pagination/paginator.rb
 - lib/rails_cursor_pagination/version.rb
 homepage: https://github.com/xing/rails_cursor_pagination
@@ -49,6 +50,7 @@ metadata:
   homepage_uri: https://github.com/xing/rails_cursor_pagination
   source_code_uri: https://github.com/xing/rails_cursor_pagination
   changelog_uri: https://github.com/xing/rails_cursor_pagination/blob/master/CHANGELOG.md
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -57,14 +59,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.5.0
+      version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.4
+rubygems_version: 3.1.6
 signing_key:
 specification_version: 4
 summary: Add cursor pagination to your ActiveRecord backed application.