cursor_pager 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1cfa8e486f765f437f2737c1778ea9f70c22849d8e0a6912bee1ec20440487a2
-  data.tar.gz: 99bbe1f36e20d8574217ca27f6bec0ef431487679f048ce7e6fb55fb8c73de5e
+  metadata.gz: 2cae99728d5827015878e6af2b7e5b06851984dec3e82f6b7ffce0e471ecab1c
+  data.tar.gz: 548d5f8799dd7748837a083ef9ec8cc8f620ede7a29107ddb7c20be28a64efb1
 SHA512:
-  metadata.gz: fe4e2e39e9d28cb318b6da7d09368f2d866a2f5386e796f8f816af22fdada3539748c46e59259c51673eee30ddb5d6059d0e02a8f6800da936be6fe1db7af6ae
-  data.tar.gz: 0e861720ee32d06b9d55c58a0f0a4ff6ba316435ae619186b8f762c42a6df40db87c79e7d968517d899fe3be3777dc146641dfa79dcada4f66883bc6e6686c48
+  metadata.gz: f84865be5f0153580346a191e58dc8483abc2a3699a358a38a2d6117624610c102fdde004b9a785b07b2095141be06e385416c5f0b94b30f2a22b0bfb1572c2d
+  data.tar.gz: e7131697760670148494e697db0579dc3d96486d09fe945552bbe22d824654afb827c0392e86099725aa48a8c72d8e4c26bcc0ffb5ffcb77561c490a09c47390

data/.rubocop.yml

@@ -18,5 +18,8 @@ Metrics/BlockLength:
   Exclude:
     - /**/spec/**/*
 
+Metrics/ClassLength:
+  Max: 200
+
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -5,4 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## [Unreleased]
+
+## [0.2.0] - 2020-04-23
+
+### Added
+
+* `first_cursor` & `last_cursor` convenience methods
+* Configurable default & maximum page sizes #6
+
+## [0.1.0] - 2020-04-23
+
+### Added
+
+* First implementation of cursor-pased pagination #2
+* Configurable cursor encoder #3
+
+[Unreleased]: https://github.com/askcharlie/cursor_pager/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/askcharlie/cursor_pager/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/askcharlie/cursor_pager/releases/tag/v0.1.0

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    cursor_pager (0.1.0)
+    cursor_pager (0.2.0)
       activerecord (>= 5.2.0)
 
 GEM

data/README.md

@@ -1,6 +1,6 @@
 # CursorPager
 
-![build](https://github.com/askcharlie/cursor_pager/workflows/CI/badge.svg)
+![build](https://github.com/askcharlie/cursor_pager/workflows/CI/badge.svg) [![Gem Version](https://badge.fury.io/rb/cursor_pager.svg)](https://badge.fury.io/rb/cursor_pager)
 
 A small and easy-to-use library that aims to make it easy to build Rails APIs
 with cursor-based pagination (aka keyset pagination).
@@ -45,7 +45,9 @@ To get information about the page or generate a cursor
 ```ruby
 page.previous_page?                # Tells you if there is a previous page
 page.next_page?                    # Tells you if there is a next page
-page.cursor_for(page.records.last) # Will generate a cursor for a specific item
+page.cursor_for(page.records.last) # Generates a cursor for a specific item
+page.first_cursor                  # Generates a cursor for the first item
+page.last_cursor                   # Generates a cursor for the last item
 ```
 
 To fetch the first then usres after a certain cursor
@@ -65,6 +67,8 @@ page.records
 
 ## Configuration
 
+### Encoder
+
 By default cursors are base64 encoded primary keys of the records. If you wish
 to change that because you want to add encryption or something similiar, you
 can provide your own encoder class.
@@ -85,6 +89,18 @@ CursorPager.configure do |config|
 end
 ```
 
+### Default & Maximum Page Size
+
+The default & maximum page sizes are configured as `nil` (unlimited) by default.
+You can however set your own values.
+
+```ruby
+CursorPager.configure do |config|
+  config.default_page_size = 25
+  config.maximum_page_size = 100
+end
+```
+
 ## Not (yet) supported
 
 * Ordering by SQL alias or function

data/lib/cursor_pager/configuration.rb

@@ -5,10 +5,24 @@ module CursorPager
   # Encapulates all the configuration for the library.
   class Configuration
     # The encoder that will be used to encode & decode cursors.
+    # Defaults to `Base64Encoder`.
     attr_accessor :encoder
 
+    # The default page size that will be used if no `first` or `last` were
+    # specified. Every record fitting the cursor constraints will be returned
+    # if it's set to `nil`.
+    # Defaults to `nil`.
+    attr_accessor :default_page_size
+
+    # The maximum allowed page size. Clients will never receive more records per
+    # page than is sepcified here. There is no maximum if this is set to `nil`.
+    # Defaults to `nil`.
+    attr_accessor :maximum_page_size
+
     def initialize
       @encoder = Base64Encoder
+      @default_page_size = nil
+      @maximum_page_size = nil
     end
   end
 

data/lib/cursor_pager/page.rb

@@ -3,12 +3,19 @@
 module CursorPager
   # The main class that coordinates the whole pagination.
   class Page
-    attr_reader :relation, :first, :last, :after, :before, :order_values
+    extend Forwardable
+
+    attr_reader :relation, :first_value, :last_value, :after, :before,
+      :order_values
+
+    def_delegators :@configuration, :encoder, :default_page_size,
+      :maximum_page_size
 
     def initialize(relation, first: nil, last: nil, after: nil, before: nil)
+      @configuration = CursorPager.configuration
       @relation = relation
-      @first = first
-      @last = last
+      @first_value = first
+      @last_value = last
       @after = after
       @before = before
       @order_values = OrderValues.from_relation(relation)
@@ -17,6 +24,28 @@ module CursorPager
       verify_order_directions!
     end
 
+    # A capped `first` value.
+    # The underlying instance variable `first_value` doesn't have limits on it.
+    # If neither `first` nor `last` is given, but `default_page_size` or
+    # `maximum_page_size` are configured, they will be used for first.
+    def first
+      @first ||= begin
+                   capped = limit_pagination_argument(first_value)
+
+                   if capped.nil? && last.nil?
+                     capped = default_page_size || maximum_page_size
+                   end
+
+                   capped
+                 end
+    end
+
+    # A capped `last` value.
+    # The underlying instance variable `last_value` doesn't have limits on it.
+    def last
+      @last ||= limit_pagination_argument(last_value)
+    end
+
     def previous_page?
       @previous_page ||= if after_limit_value.present?
                            true
@@ -38,9 +67,19 @@ module CursorPager
     end
 
     def cursor_for(item)
+      return if item.nil?
+
       encoder.encode(item.id.to_s)
     end
 
+    def first_cursor
+      cursor_for(records.first)
+    end
+
+    def last_cursor
+      cursor_for(records.last)
+    end
+
     def records
       @records ||= limited_relation.to_a
     end
@@ -67,6 +106,21 @@ module CursorPager
       raise ConflictingOrdersError
     end
 
+    # Used to cap `first` and `last` arguments.
+    # Returns `nil` if the argument is `nil`, otherwise a value between `0` and
+    # `maximum_page_size`.
+    def limit_pagination_argument(argument)
+      return if argument.nil?
+
+      if argument.negative?
+        argument = 0
+      elsif maximum_page_size && argument > maximum_page_size
+        argument = maximum_page_size
+      end
+
+      argument
+    end
+
     def limited_relation
       @limited_relation ||= LimitRelation.new(sliced_relation, first, last).call
     end
@@ -102,9 +156,5 @@ module CursorPager
 
       order_values.map { |value| item[value.select_alias] }
     end
-
-    def encoder
-      CursorPager.configuration.encoder
-    end
   end
 end

data/lib/cursor_pager/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CursorPager
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: cursor_pager
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Bastian Bartmann
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-23 00:00:00.000000000 Z
+date: 2020-04-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord