geared_pagination 0.2 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: f2ef2f3f5dc638b5cd4b6ab2459cbf4e513b85e4
-  data.tar.gz: 3ae73c3c52ee2dd1a257daff921cabe401373733
+SHA256:
+  metadata.gz: 6442a3bf0d55e8a7959814c6fd7d7e02da254952dbd829493aaf99c01bdd85f4
+  data.tar.gz: d064b59363360f871c6cc91adcce01d4a863d6379282fabb354fbeea0f402cfb
 SHA512:
-  metadata.gz: a66259e261f8f9b98459cbd754039fbfb304fd8c700181b3babb4dca4ceeb83efb2e49dbf1e00d1238ede83f1ddbc9d96812cdf603c5e0644bd2d59969fab21a
-  data.tar.gz: ba3b678d00e7615b1c8595ca342bd2d9cd1f4dee75a2e20f5ab93f178caf19b25b6d2abd6af3a4eb26b8dcf798ecee69a21d231fd4637e22a33f3fe9ce1087aa
+  metadata.gz: becae20eab1dd38355befb8a1440dcd432c0743f94d59f27f7323a7a2386849736605c96ddb344aa45d039569d4a5b406d0732fec2576cdbe093a602084e4fbc
+  data.tar.gz: 066f7da6d2db1875602aeb1517bf0cb19be41fc142dd3104cd68e0e204b77c3f196cac3ca19604ef75132424a7c6d988352c2e5d5ee1ed651047b4680d5c0c6c

data/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v1
+
+      - name: Set up Ruby 2.6
+        uses: actions/setup-ruby@v1
+        with:
+          ruby-version: 2.6.x
+
+      - name: Cache gem dependencies
+        uses: actions/cache@v1
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-bundler-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: ${{ runner.os }}-bundler-
+
+      - name: Install system dependencies
+        run: sudo apt-get update && sudo apt-get install libsqlite3-dev
+
+      - name: Install gem dependencies
+        run:  gem install bundler && bundle install --jobs 4 --retry 3 --path vendor/bundle
+
+      - name: Run tests
+        run: bundle exec rake test

data/.gitignore

@@ -0,0 +1,9 @@
+.byebug_history
+
+test/dummy/db/*.sqlite3
+test/dummy/db/*.sqlite3-journal
+test/dummy/log/*.log
+test/dummy/node_modules/
+test/dummy/yarn-error.log
+test/dummy/storage/
+test/dummy/tmp/

data/Gemfile

@@ -4,4 +4,6 @@ gemspec
 
 gem 'rake'
 gem 'byebug'
-gem 'actionpack', '>= 5'
+
+gem 'rails', '>= 5.0'
+gem 'sqlite3'

data/Gemfile.lock

@@ -1,67 +1,152 @@
 PATH
   remote: .
   specs:
-    geared_pagination (0.1)
+    geared_pagination (0.2)
       activesupport (>= 5.0)
       addressable (>= 2.5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    actionpack (5.0.2)
-      actionview (= 5.0.2)
-      activesupport (= 5.0.2)
-      rack (~> 2.0)
-      rack-test (~> 0.6.3)
+    actioncable (6.0.3)
+      actionpack (= 6.0.3)
+      nio4r (~> 2.0)
+      websocket-driver (>= 0.6.1)
+    actionmailbox (6.0.3)
+      actionpack (= 6.0.3)
+      activejob (= 6.0.3)
+      activerecord (= 6.0.3)
+      activestorage (= 6.0.3)
+      activesupport (= 6.0.3)
+      mail (>= 2.7.1)
+    actionmailer (6.0.3)
+      actionpack (= 6.0.3)
+      actionview (= 6.0.3)
+      activejob (= 6.0.3)
+      mail (~> 2.5, >= 2.5.4)
       rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.2)
-    actionview (5.0.2)
-      activesupport (= 5.0.2)
+    actionpack (6.0.3)
+      actionview (= 6.0.3)
+      activesupport (= 6.0.3)
+      rack (~> 2.0, >= 2.0.8)
+      rack-test (>= 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.2.0)
+    actiontext (6.0.3)
+      actionpack (= 6.0.3)
+      activerecord (= 6.0.3)
+      activestorage (= 6.0.3)
+      activesupport (= 6.0.3)
+      nokogiri (>= 1.8.5)
+    actionview (6.0.3)
+      activesupport (= 6.0.3)
       builder (~> 3.1)
-      erubis (~> 2.7.0)
+      erubi (~> 1.4)
       rails-dom-testing (~> 2.0)
-      rails-html-sanitizer (~> 1.0, >= 1.0.3)
-    activesupport (5.0.2)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activejob (6.0.3)
+      activesupport (= 6.0.3)
+      globalid (>= 0.3.6)
+    activemodel (6.0.3)
+      activesupport (= 6.0.3)
+    activerecord (6.0.3)
+      activemodel (= 6.0.3)
+      activesupport (= 6.0.3)
+    activestorage (6.0.3)
+      actionpack (= 6.0.3)
+      activejob (= 6.0.3)
+      activerecord (= 6.0.3)
+      marcel (~> 0.3.1)
+    activesupport (6.0.3)
       concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (~> 0.7)
+      i18n (>= 0.7, < 2)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    addressable (2.5.1)
-      public_suffix (~> 2.0, >= 2.0.2)
-    builder (3.2.3)
-    byebug (9.0.6)
-    concurrent-ruby (1.0.5)
-    erubis (2.7.0)
-    i18n (0.8.1)
-    loofah (2.0.3)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    addressable (2.5.2)
+      public_suffix (>= 2.0.2, < 4.0)
+    builder (3.2.4)
+    byebug (10.0.2)
+    concurrent-ruby (1.1.6)
+    crass (1.0.6)
+    erubi (1.9.0)
+    globalid (0.4.2)
+      activesupport (>= 4.2.0)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    loofah (2.5.0)
+      crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
-    mini_portile2 (2.1.0)
-    minitest (5.10.1)
-    nokogiri (1.7.1)
-      mini_portile2 (~> 2.1.0)
-    public_suffix (2.0.5)
-    rack (2.0.1)
-    rack-test (0.6.3)
-      rack (>= 1.0)
-    rails-dom-testing (2.0.2)
-      activesupport (>= 4.2.0, < 6.0)
-      nokogiri (~> 1.6)
-    rails-html-sanitizer (1.0.3)
-      loofah (~> 2.0)
-    rake (12.0.0)
+    mail (2.7.1)
+      mini_mime (>= 0.1.1)
+    marcel (0.3.3)
+      mimemagic (~> 0.3.2)
+    method_source (1.0.0)
+    mimemagic (0.3.5)
+    mini_mime (1.0.2)
+    mini_portile2 (2.4.0)
+    minitest (5.14.0)
+    nio4r (2.5.2)
+    nokogiri (1.10.9)
+      mini_portile2 (~> 2.4.0)
+    public_suffix (3.0.3)
+    rack (2.2.2)
+    rack-test (1.1.0)
+      rack (>= 1.0, < 3)
+    rails (6.0.3)
+      actioncable (= 6.0.3)
+      actionmailbox (= 6.0.3)
+      actionmailer (= 6.0.3)
+      actionpack (= 6.0.3)
+      actiontext (= 6.0.3)
+      actionview (= 6.0.3)
+      activejob (= 6.0.3)
+      activemodel (= 6.0.3)
+      activerecord (= 6.0.3)
+      activestorage (= 6.0.3)
+      activesupport (= 6.0.3)
+      bundler (>= 1.3.0)
+      railties (= 6.0.3)
+      sprockets-rails (>= 2.0.0)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.3.0)
+      loofah (~> 2.3)
+    railties (6.0.3)
+      actionpack (= 6.0.3)
+      activesupport (= 6.0.3)
+      method_source
+      rake (>= 0.8.7)
+      thor (>= 0.20.3, < 2.0)
+    rake (13.0.1)
+    sprockets (4.0.0)
+      concurrent-ruby (~> 1.0)
+      rack (> 1, < 3)
+    sprockets-rails (3.2.1)
+      actionpack (>= 4.0)
+      activesupport (>= 4.0)
+      sprockets (>= 3.0.0)
+    sqlite3 (1.4.2)
+    thor (1.0.1)
     thread_safe (0.3.6)
-    tzinfo (1.2.3)
+    tzinfo (1.2.7)
       thread_safe (~> 0.1)
+    websocket-driver (0.7.1)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.4)
+    zeitwerk (2.3.0)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  actionpack (>= 5)
   bundler (~> 1.12)
   byebug
   geared_pagination!
+  rails (>= 5.0)
   rake
+  sqlite3
 
 BUNDLED WITH
-   1.14.6
+   1.17.2

data/README.md

@@ -30,12 +30,57 @@ Showing page <%= @page.number %> of <%= @page.recordset.page_count %> (<%= @page
 
 <% if @page.last? %>
   No more pages!
-<% else %> 
-  <%= link_to "Next page", messages_path(page: @page.next_number) %>
+<% else %>
+  <%= link_to "Next page", messages_path(page: @page.next_param) %>
 <% end %>
 
 ```
 
+## Cursor-based pagination
+
+By default, Geared Pagination uses *offset-based pagination*: the `page` query parameter contains the page number. Each page’s records are located using a query with an `OFFSET` clause, like so:
+
+```sql
+SELECT *
+FROM messages
+ORDER BY created_at DESC
+LIMIT 30
+OFFSET 15
+```
+
+You may prefer to use *cursor-based pagination* instead. In cursor-based pagination, the `page` parameter contains a “cursor” describing the last row of the previous page. Each page’s records are located using a query with conditions that only match records after the previous page. For example, if the last record on the previous page had a `created_at` value of `2019-01-24T12:35:26.381Z` and an ID of `7354857`, the current page’s records would be found with a query like this one:
+
+```sql
+SELECT *
+FROM messages
+WHERE (created_at = '2019-01-24T12:35:26.381Z' AND id < 7354857)
+OR created_at < '2019-01-24T12:35:26.381Z'
+ORDER BY created_at DESC, id DESC
+LIMIT 30
+```
+
+Geared Pagination supports cursor-based pagination. To use it, pass the `:order_by` option to `set_page_and_extract_portion_from` in your controllers. Provide the orders to apply to the paginated relation:
+
+```ruby
+set_page_and_extract_portion_from Message.all, ordered_by: { created_at: :desc, id: :desc }
+```
+
+Geared Pagination uses the ordered attributes (in the above example, `created_at` and `id`) to generate cursors:
+
+```erb
+<%= link_to "Next page", messages_path(page: @page.next_param) %>
+<!-- <a href="/messages?page=eyJwYWdlX251...">Next page</a> -->
+```
+
+Cursors encode the information Geared Pagination needs to query for the corresponding page’s records: the page number for choosing a page size, and the values of each of the ordered attributes (`created_at` and `id`).
+
+### When should I use cursor-based pagination?
+
+Cursor-based pagination can outperform offset-based pagination when paginating deeply into a large number of records. DBs commonly execute queries with `OFFSET` clauses by counting past `OFFSET` records one at a time, so each page in offset-based pagination takes slightly longer to load than the last. With cursor-based pagination and an appropriate index, the DB can jump directly to the beginning of each page without scanning.
+
+The tradeoff is that Geared Pagination only supports cursor-based pagination on simple relations with simple, column-only orders. Cursor-based pagination also won’t perform better than offset-based pagination without an ordered index. Stick with offset-based pagination if:
+* You need complex ordering on a complex relation
+* You’re paginating a small and/or bounded number of records
 
 ## Caching
 

data/Rakefile

@@ -5,6 +5,7 @@ require "rake/testtask"
 Rake::TestTask.new do |test|
   test.libs << "test"
   test.test_files = FileList["test/*_test.rb"]
+  test.warning = false
 end
 
 task default: :test

data/bin/rails

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# This command will automatically be run when you run "rails" with Rails gems
+# installed from the root of your application.
+
+ENGINE_ROOT = File.expand_path('..', __dir__)
+ENGINE_PATH = File.expand_path('../lib/geared_pagination/engine', __dir__)
+APP_PATH = File.expand_path('../test/dummy/config/application', __dir__)
+
+# Set up gems listed in the Gemfile.
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path('../Gemfile', __dir__)
+require 'bundler/setup' if File.exist?(ENV['BUNDLE_GEMFILE'])
+
+require 'rails'
+require 'action_controller/railtie'
+require 'rails/test_unit/railtie'
+require 'rails/engine/commands'

data/geared_pagination.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name     = 'geared_pagination'
-  s.version  = '0.2'
+  s.version  = '1.0.0'
   s.authors  = 'David Heinemeier Hansson'
   s.email    = 'david@basecamp.com'
   s.summary  = 'Paginate Active Record sets at variable speeds'
@@ -14,6 +14,6 @@ Gem::Specification.new do |s|
 
   s.add_development_dependency 'bundler', '~> 1.12'
 
-  s.files         = `git ls-files`.split("\n")
-  s.test_files    = `git ls-files -- test/*`.split("\n")
+  s.files      = `git ls-files`.split("\n")
+  s.test_files = `git ls-files -- test/*`.split("\n")
 end

data/lib/geared_pagination.rb

@@ -1,2 +1,2 @@
 require 'geared_pagination/recordset'
-require 'geared_pagination/railtie' if defined?(Rails)
+require 'geared_pagination/engine' if defined?(Rails)

data/lib/geared_pagination/controller.rb

@@ -11,13 +11,13 @@ module GearedPagination
     end
 
     private
-      def set_page_and_extract_portion_from(records, per_page: nil)
-        @page = current_page_from(records, per_page: per_page)
+      def set_page_and_extract_portion_from(records, ordered_by: nil, per_page: nil)
+        @page = current_page_from(records, ordered_by: ordered_by, per_page: per_page)
         @page.records
       end
 
-      def current_page_from(records, per_page: nil)
-        GearedPagination::Recordset.new(records, per_page: per_page).page(current_page_param)
+      def current_page_from(records, ordered_by: nil, per_page: nil)
+        GearedPagination::Recordset.new(records, ordered_by: ordered_by, per_page: per_page).page(current_page_param)
       end
 
       def set_paginated_headers
@@ -29,7 +29,7 @@ module GearedPagination
       end
 
       def current_page_param
-        params[:page].to_i > 0 ? params[:page].to_i : 1
+        params[:page]
       end
   end
 end

data/lib/geared_pagination/cursor.rb

@@ -0,0 +1,40 @@
+require 'base64'
+require 'active_support/json'
+
+module GearedPagination
+  class Cursor
+    class << self
+      def from_param(key)
+        key.present? ? decode(key) : new
+      end
+
+      def decode(key)
+        if attributes = ActiveSupport::JSON.decode(Base64.urlsafe_decode64(key))
+          new **attributes.deep_symbolize_keys
+        end
+      end
+
+      def encode(page_number: 1, values: {})
+        Base64.urlsafe_encode64 ActiveSupport::JSON.encode(page_number: page_number, values: values)
+      end
+    end
+
+    attr_reader :values
+
+    def initialize(page_number: 1, values: {})
+      @page_number, @values = page_number, values
+    end
+
+    def page_number
+      @page_number > 0 ? @page_number : 1
+    end
+
+    def fetch(attribute)
+      values.fetch(attribute)
+    end
+
+    def include?(attribute)
+      values.include?(attribute)
+    end
+  end
+end

data/lib/geared_pagination/{railtie.rb → engine.rb}

@@ -1,4 +1,4 @@
-require 'rails/railtie'
+require 'rails/engine'
 require 'geared_pagination/controller'
 
 class GearedPagination::Engine < ::Rails::Engine

data/lib/geared_pagination/headers.rb

@@ -7,29 +7,36 @@ module GearedPagination
     end
 
     def apply
-      @controller.headers.update(headers) if applicable?
+      controller.headers.update(headers) if applicable?
     end
 
     private
+      attr_reader :page, :controller
+      delegate :request, to: :controller
+
       def headers
         Hash.new.tap do |h|
-          h["X-Total-Count"] = @page.recordset.records_count.to_s
-          h["Link"] = next_page_link_header unless @page.last?
+          h["X-Total-Count"] = page.recordset.records_count.to_s
+          h["Link"] = next_page_link_header unless page.last?
         end
       end
 
       def applicable?
-        @controller.request.format&.json?
+        request.format&.json?
       end
 
       def next_page_link_header
-        link_header(rel: :next, page_number: @page.next_number).to_s
+        link_header(rel: :next, page: page.next_param).to_s
+      end
+
+      def link_header(rel:, page:)
+        %{<#{uri(page: page)}>; rel="#{rel}"}
       end
 
-      def link_header(rel:, page_number:)
-        uri = Addressable::URI.parse(@controller.request.url)
-        uri.query_values = (uri.query_values || {}).merge("page" => page_number)
-        %{<#{uri}>; rel="#{rel}"}
+      def uri(page:)
+        Addressable::URI.parse(request.url).tap do |uri|
+          uri.query_values = (uri.query_values || {}).merge("page" => page)
+        end.to_s
       end
   end
 end