geared_pagination 0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 86fef30f9fb2e850e8b305a079d05d39007ec6bd
-  data.tar.gz: 83e91624d0fbd65747604f91628e826f00a131b0
+SHA256:
+  metadata.gz: 05c58b3498b3b341fd11f5500545278837414633b714f7c02aca2c3718c86227
+  data.tar.gz: b3c4729222ff73faf62566f48187ae522544a1491a6fba02ff4b921e24c1dcbd
 SHA512:
-  metadata.gz: f7e00eb4a7598860c873eb1810ffdba1c8e5a30d625d42b6a7e10f035786e593724b74c8c496089495ada18c992af7b41534041e1b5951f8573932a3d533509e
-  data.tar.gz: c2feb3068a763034a474fca15cd793b3fdeae695cee4c6f0187c4ea2918a76a24f9a124061407922a3b397137119fdc234413153563ba0ed9f3301af9204238e
+  metadata.gz: c327c83175f3a27a8a91732ab3ae81c3c5d0f0da3ef54726a0d30042e7bb90b4ba933781ccee5b57cc7808c477e9bb12b5e67204e0c2417450a82350eeeadacf
+  data.tar.gz: ed877d95bad4a4d4083ee05f02d7211aa9e28c96eaf948cd387baa7b930373d5e08227024268bd1efef46c8fa75f84ac71c297a9080626c9c39ce8148e6e1e1c

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,10 @@
+*.gem
+.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

@@ -3,4 +3,7 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rake'
-gem 'byebug'
+gem 'byebug'
+
+gem 'rails', '>= 5.0'
+gem 'sqlite3'

data/Gemfile.lock

@@ -1,29 +1,141 @@
 PATH
   remote: .
   specs:
-    geared_pagination (0.1)
+    geared_pagination (1.1.0)
       activesupport (>= 5.0)
       addressable (>= 2.5.0)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.1.0.beta1)
+    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)
+    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)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      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.0)
-      public_suffix (~> 2.0, >= 2.0.2)
-    byebug (9.0.6)
-    concurrent-ruby (1.0.4)
-    i18n (0.8.1)
-    minitest (5.10.1)
-    public_suffix (2.0.5)
-    rake (12.0.0)
-    thread_safe (0.3.5)
-    tzinfo (1.2.2)
+      zeitwerk (~> 2.2, >= 2.2.2)
+    addressable (2.7.0)
+      public_suffix (>= 2.0.2, < 5.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)
+    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 (4.0.6)
+    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.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
@@ -32,7 +144,9 @@ DEPENDENCIES
   bundler (~> 1.12)
   byebug
   geared_pagination!
+  rails (>= 5.0)
   rake
+  sqlite3
 
 BUNDLED WITH
-   1.14.6
+   1.17.2

data/README.md

@@ -1,40 +1,107 @@
 # Geared Pagination
 
 Most pagination schemes use a fixed page size. Page 1 returns as many elements as page 2. But that's
-frequently not the most sensible way to page through a large collection when you care about serving the
+frequently not the most sensible way to page through a large recordset when you care about serving the
 initial request as quickly as possible. This is particularly the case when using the pagination scheme
 in combination with an infinite scrolling UI.
 
 Geared Pagination allows you to define different ratios. By default, we will return 15 elements on page 1,
-30 on page 2, 50 on page 3, and 100 from page 4 and forward. This has proben to be a very sensible set of
+30 on page 2, 50 on page 3, and 100 from page 4 and forward. This has proven to be a very sensible set of
 ratios for much of the Basecamp UIs. But you can of course tweak the ratios, use fewer, or even none at all,
-if you certain page calls for a fixed-rate scheme.
+if a certain page calls for a fixed-rate scheme.
 
-On json actions that set a page, we'll also also automatically set Link and X-Total-Count headers for APIs
-to be able to page through a collection.
+On JSON actions that set a page, we'll also automatically set Link and X-Total-Count headers for APIs
+to be able to page through a recordset.
 
 ## Example
 
 ```ruby
 class MessagesController < ApplicationController
   def index
-    @page = current_page_from Message.order(created_at: :desc)
+    set_page_and_extract_portion_from Message.order(created_at: :desc)
   end
 end
 
 # app/views/messages/index.html.erb
 
-Showing page <%= @page.number %> of <%= @page.collection.page_count %> (<%= @page.collection.record_count %> total messages):
+Showing page <%= @page.number %> of <%= @page.recordset.page_count %> (<%= @page.recordset.records_count %> total messages):
 
 <%= render @page.records %>
 
 <% 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 `:ordered_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
+
+To account for the current page in fragment caches, include the `@page` directly.
+That includes the current page number and gear ratios.
+
+Fragment caching a message's comments:
+```ruby
+<% cache [ @message, @page ] do %>
+  <%= render @page.records %>
+<% end %>
+```
+
+NOTE: The page does not include cache keys for all the records. That would require loading all the records,
+defeating the purpose of using the cache. Use a parent record, like a message that's touched when
+new comments are posted, as the cache key instead.
+
+## ETags
+
+When a controller action sets an ETag and uses geared pagination, the current page and gear ratios are
+automatically included in the ETag.
+
 ## License
 Geared Pagination is released under the [MIT License](https://opensource.org/licenses/MIT).

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.1'
+  s.version  = '1.1.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

@@ -7,24 +7,29 @@ module GearedPagination
 
     included do
       after_action :set_paginated_headers
+      etag { @page if geared_page? }
     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
-        GearedPagination::Headers.new(page: @page, controller: self).apply if @page.is_a?(GearedPagination::Page)
+        GearedPagination::Headers.new(page: @page, controller: self).apply if geared_page?
+      end
+
+      def geared_page?
+        @page.is_a? GearedPagination::Page
       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