geared_pagination 0.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 86fef30f9fb2e850e8b305a079d05d39007ec6bd
-  data.tar.gz: 83e91624d0fbd65747604f91628e826f00a131b0
+  metadata.gz: f2ef2f3f5dc638b5cd4b6ab2459cbf4e513b85e4
+  data.tar.gz: 3ae73c3c52ee2dd1a257daff921cabe401373733
 SHA512:
-  metadata.gz: f7e00eb4a7598860c873eb1810ffdba1c8e5a30d625d42b6a7e10f035786e593724b74c8c496089495ada18c992af7b41534041e1b5951f8573932a3d533509e
-  data.tar.gz: c2feb3068a763034a474fca15cd793b3fdeae695cee4c6f0187c4ea2918a76a24f9a124061407922a3b397137119fdc234413153563ba0ed9f3301af9204238e
+  metadata.gz: a66259e261f8f9b98459cbd754039fbfb304fd8c700181b3babb4dca4ceeb83efb2e49dbf1e00d1238ede83f1ddbc9d96812cdf603c5e0644bd2d59969fab21a
+  data.tar.gz: ba3b678d00e7615b1c8595ca342bd2d9cd1f4dee75a2e20f5ab93f178caf19b25b6d2abd6af3a4eb26b8dcf798ecee69a21d231fd4637e22a33f3fe9ce1087aa

data/Gemfile

@@ -3,4 +3,5 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'rake'
-gem 'byebug'
+gem 'byebug'
+gem 'actionpack', '>= 5'

data/Gemfile.lock

@@ -8,27 +8,56 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (5.1.0.beta1)
+    actionpack (5.0.2)
+      actionview (= 5.0.2)
+      activesupport (= 5.0.2)
+      rack (~> 2.0)
+      rack-test (~> 0.6.3)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.2)
+    actionview (5.0.2)
+      activesupport (= 5.0.2)
+      builder (~> 3.1)
+      erubis (~> 2.7.0)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.0, >= 1.0.3)
+    activesupport (5.0.2)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (~> 0.7)
       minitest (~> 5.1)
       tzinfo (~> 1.1)
-    addressable (2.5.0)
+    addressable (2.5.1)
       public_suffix (~> 2.0, >= 2.0.2)
+    builder (3.2.3)
     byebug (9.0.6)
-    concurrent-ruby (1.0.4)
+    concurrent-ruby (1.0.5)
+    erubis (2.7.0)
     i18n (0.8.1)
+    loofah (2.0.3)
+      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)
-    thread_safe (0.3.5)
-    tzinfo (1.2.2)
+    thread_safe (0.3.6)
+    tzinfo (1.2.3)
       thread_safe (~> 0.1)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  actionpack (>= 5)
   bundler (~> 1.12)
   byebug
   geared_pagination!

data/README.md

@@ -1,30 +1,30 @@
 # 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 %>
 
@@ -36,5 +36,27 @@ Showing page <%= @page.number %> of <%= @page.collection.page_count %> (<%= @pag
 
 ```
 
+
+## 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/geared_pagination.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name     = 'geared_pagination'
-  s.version  = '0.1'
+  s.version  = '0.2'
   s.authors  = 'David Heinemeier Hansson'
   s.email    = 'david@basecamp.com'
   s.summary  = 'Paginate Active Record sets at variable speeds'

data/lib/geared_pagination/controller.rb

@@ -7,6 +7,7 @@ module GearedPagination
 
     included do
       after_action :set_paginated_headers
+      etag { @page if geared_page? }
     end
 
     private
@@ -20,7 +21,11 @@ module GearedPagination
       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

data/lib/geared_pagination/headers.rb

@@ -13,7 +13,7 @@ module GearedPagination
     private
       def headers
         Hash.new.tap do |h|
-          h["X-Total-Count"] = @page.collection.records_count.to_s
+          h["X-Total-Count"] = @page.recordset.records_count.to_s
           h["Link"] = next_page_link_header unless @page.last?
         end
       end

data/lib/geared_pagination/page.rb

@@ -2,15 +2,15 @@ require 'geared_pagination/portion'
 
 module GearedPagination
   class Page
-    attr_reader :number, :collection
+    attr_reader :number, :recordset
 
     def initialize(number, from:)
-      @number, @collection = number, from
+      @number, @recordset = number, from
       @portion = GearedPagination::Portion.new(page_number: number, per_page: from.ratios)
     end
 
     def records
-      @records ||= @portion.from(collection.records)
+      @records ||= @portion.from(recordset.records)
     end
 
 
@@ -28,16 +28,21 @@ module GearedPagination
     end
 
     def only?
-      collection.page_count == 1
+      recordset.page_count == 1
     end
 
     def last?
-      number == collection.page_count
+      number == recordset.page_count
     end
 
 
     def next_number
       number + 1
     end
+
+
+    def cache_key
+      "page/#{@portion.cache_key}"
+    end
   end
 end

data/lib/geared_pagination/portion.rb

@@ -19,5 +19,10 @@ module GearedPagination
     def offset
       (page_number - 1).times.sum { |index| ratios[index + 1] }
     end
+
+
+    def cache_key
+      "#{page_number}:#{ratios.cache_key}"
+    end
   end
 end

data/lib/geared_pagination/railtie.rb

@@ -2,7 +2,7 @@ require 'rails/railtie'
 require 'geared_pagination/controller'
 
 class GearedPagination::Engine < ::Rails::Engine
-  initializer :webpacker do |app|
+  initializer :geared_pagination do |app|
     ActiveSupport.on_load :action_controller do
       ActionController::Base.send :include, GearedPagination::Controller
     end

data/lib/geared_pagination/ratios.rb

@@ -9,5 +9,9 @@ module GearedPagination
     def [](page_number)
       @ratios[page_number - 1] || @ratios.last
     end
+
+    def cache_key
+      @ratios.join('-')
+    end
   end
 end

data/lib/geared_pagination/recordset.rb

@@ -24,7 +24,7 @@ module GearedPagination
           residual = residual - ratios[count]
         end
 
-        count
+        count > 0 ? count : 1
       end
     end
 

data/test/controller_test.rb

@@ -0,0 +1,66 @@
+require 'test_helper'
+require 'geared_pagination'
+require 'geared_pagination/controller'
+require 'active_support/all'
+require 'action_controller'
+
+class RecordingsController < ActionController::Base
+  include GearedPagination::Controller
+
+  def index
+    set_page_and_extract_portion_from Recording.all, per_page: params[:per_page]
+    render json: @page.records if stale? etag: "placeholder"
+  end
+
+  def unpaged
+    @page = "not a geared pagination page"
+    head :ok if stale? etag: "placeholder"
+  end
+end
+
+class GearedPagination::ControllerTest < ActionController::TestCase
+  tests RecordingsController
+
+  setup do
+    @routes = ActionDispatch::Routing::RouteSet.new.tap do |r|
+      r.draw do
+        resources :recordings do
+          get :unpaged, on: :collection
+        end
+      end
+    end
+  end
+
+  test "ETag includes the current page and gearing" do
+    get :index, params: { per_page: [ 1, 2 ] }
+    assert_equal etag_for("placeholder", "page/1:1-2"), response.etag
+    etag_before_gearing_change = response.etag
+
+    get :index, params: { page: 1, per_page: [ 1, 2 ] }
+    assert_equal etag_before_gearing_change, response.etag
+
+    get :index, params: { page: 1, per_page: [ 1, 3 ] }
+    assert_not_equal etag_before_gearing_change, response.etag
+  end
+
+  test "ETag is ignored when @page is not a geared page" do
+    get :unpaged
+    assert_equal etag_for("placeholder"), response.etag
+  end
+
+  test "Link headers on JSON requests" do
+    get :index, format: 'json'
+    assert_equal "120", response.headers["X-Total-Count"]
+    assert_equal '<http://test.host/recordings.json?page=2>; rel="next"', response.headers["Link"]
+  end
+
+  test "no Link headers on non-JSON requests" do
+    get :index
+    assert_nil response.headers["Link"]
+  end
+
+  private
+    def etag_for(*keys)
+      %(W/"#{Digest::MD5.hexdigest(ActiveSupport::Cache.expand_cache_key(keys))}")
+    end
+end

data/test/headers_test.rb

@@ -8,40 +8,40 @@ class GearedPagination::HeadersTest < ActiveSupport::TestCase
   Controller = Struct.new(:request, :headers)
 
   setup do
-    @controller_serving_json = Controller.new(Request.new("http://example.com/collection.json", "json".inquiry), {})
-    @controller_serving_html = Controller.new(Request.new("http://example.com/collection", "html".inquiry), {})
+    @controller_serving_json = Controller.new(Request.new("http://example.com/recordset.json", "json".inquiry), {})
+    @controller_serving_html = Controller.new(Request.new("http://example.com/recordset", "html".inquiry), {})
 
-    @single_page_collection = GearedPagination::Recordset.new(Recording.all, per_page: 1000) 
-    @many_page_collection   = GearedPagination::Recordset.new(Recording.all, per_page: 1) 
+    @single_page_recordset = GearedPagination::Recordset.new(Recording.all, per_page: 1000) 
+    @many_page_recordset   = GearedPagination::Recordset.new(Recording.all, per_page: 1) 
   end
 
   test "total count" do
-    GearedPagination::Headers.new(page: @many_page_collection.page(1), controller: @controller_serving_json).apply
+    GearedPagination::Headers.new(page: @many_page_recordset.page(1), controller: @controller_serving_json).apply
     assert_equal Recording.all.count.to_s, @controller_serving_json.headers["X-Total-Count"]
   end
 
   test "no link for html requests" do
-    GearedPagination::Headers.new(page: @many_page_collection.page(1), controller: @controller_serving_html).apply
+    GearedPagination::Headers.new(page: @many_page_recordset.page(1), controller: @controller_serving_html).apply
     assert @controller_serving_html.headers["Link"].nil?
   end
 
   test "no link for json request with single page" do
-    GearedPagination::Headers.new(page: @many_page_collection.page(1), controller: @controller_serving_html).apply
+    GearedPagination::Headers.new(page: @many_page_recordset.page(1), controller: @controller_serving_html).apply
     assert @controller_serving_html.headers["Link"].nil?
   end
 
   test "links for json request with multiple pages" do
-    GearedPagination::Headers.new(page: @many_page_collection.page(1), controller: @controller_serving_json).apply
-    assert_equal '<http://example.com/collection.json?page=2>; rel="next"',
+    GearedPagination::Headers.new(page: @many_page_recordset.page(1), controller: @controller_serving_json).apply
+    assert_equal '<http://example.com/recordset.json?page=2>; rel="next"',
       @controller_serving_json.headers["Link"]
 
-    GearedPagination::Headers.new(page: @many_page_collection.page(2), controller: @controller_serving_json).apply
-    assert_equal '<http://example.com/collection.json?page=3>; rel="next"',
+    GearedPagination::Headers.new(page: @many_page_recordset.page(2), controller: @controller_serving_json).apply
+    assert_equal '<http://example.com/recordset.json?page=3>; rel="next"',
       @controller_serving_json.headers["Link"]
   end
 
   test "no link for json request with multiple pages on last page" do
-    GearedPagination::Headers.new(page: @many_page_collection.page(Recording.all.count), controller: @controller_serving_json).apply
+    GearedPagination::Headers.new(page: @many_page_recordset.page(Recording.all.count), controller: @controller_serving_json).apply
     assert @controller_serving_json.headers["Link"].nil?
   end
 end

data/test/page_test.rb

@@ -20,4 +20,23 @@ class GearedPagination::PageTest < ActiveSupport::TestCase
   test "next_number" do
     assert_equal 2, GearedPagination::Recordset.new(Recording.all, per_page: 1000).page(1).next_number
   end
+
+  test "with empty recordset" do
+    page_for_empty_set = GearedPagination::Recordset.new(Recordings.new([]), per_page: 1000).page(1)
+
+    assert page_for_empty_set.first?
+    assert page_for_empty_set.only?
+    assert page_for_empty_set.last?
+  end
+
+  test "cache key changes according to current page and gearing" do
+    assert_equal 'page/2:3', cache_key(page: 2, per_page: 3)
+    assert_equal 'page/2:1-3', cache_key(page: 2, per_page: [ 1, 3 ])
+    assert_equal 'page/2:2-3', cache_key(page: 2, per_page: [ 2, 3 ])
+  end
+
+  private
+    def cache_key(page:, per_page:)
+      GearedPagination::Recordset.new(Recording.all, per_page: per_page).page(page).cache_key
+    end
 end

data/test/portion_test.rb

@@ -13,4 +13,15 @@ class GearedPagination::PortionTest < ActiveSupport::TestCase
     assert_equal GearedPagination::Ratios::DEFAULTS.first, GearedPagination::Portion.new(page_number: 1).limit
     assert_equal GearedPagination::Ratios::DEFAULTS.second, GearedPagination::Portion.new(page_number: 2).limit
   end
+
+  test "cache key changes according to current page and gearing" do
+    assert_equal '2:3', cache_key(page: 2, per_page: 3)
+    assert_equal '2:1-3', cache_key(page: 2, per_page: [ 1, 3 ])
+    assert_equal '2:2-3', cache_key(page: 2, per_page: [ 2, 3 ])
+  end
+
+  private
+    def cache_key(page:, per_page:)
+      GearedPagination::Portion.new(page_number: page, per_page: GearedPagination::Ratios.new(per_page)).cache_key
+    end
 end

data/test/ratios_test.rb

@@ -24,4 +24,8 @@ class GearedPagination::RatiosTest < ActiveSupport::TestCase
     assert_equal GearedPagination::Ratios::DEFAULTS.first, limits[1]
     assert_equal GearedPagination::Ratios::DEFAULTS.last, limits[99]
   end
+
+  test "cache key" do
+    assert_equal "1-2-3", GearedPagination::Ratios.new([ 1, 2, 3 ]).cache_key
+  end
 end

data/test/recordset_test.rb

@@ -3,26 +3,26 @@ require 'geared_pagination/recordset'
 
 class GearedPagination::RecordsetTest < ActiveSupport::TestCase
   test "single limit pagination" do
-    collection = GearedPagination::Recordset.new(Recording.all, per_page: 10)
+    recordset = GearedPagination::Recordset.new(Recording.all, per_page: 10)
 
-    assert_equal 10, collection.page(1).records.size
-    assert_equal 10, collection.page(2).records.size
+    assert_equal 10, recordset.page(1).records.size
+    assert_equal 10, recordset.page(2).records.size
   end
 
   test "variable limit pagination" do
-    collection = GearedPagination::Recordset.new(Recording.all, per_page: [ 10, 15, 20 ])
+    recordset = GearedPagination::Recordset.new(Recording.all, per_page: [ 10, 15, 20 ])
 
-    assert_equal 10, collection.page(1).records.size
-    assert collection.page(1).records.include?(Recording.all[0])
+    assert_equal 10, recordset.page(1).records.size
+    assert recordset.page(1).records.include?(Recording.all[0])
 
-    assert_equal 15, collection.page(2).records.size
-    assert collection.page(2).records.include?(Recording.all[11])
+    assert_equal 15, recordset.page(2).records.size
+    assert recordset.page(2).records.include?(Recording.all[11])
 
-    assert_equal 20, collection.page(3).records.size
-    assert collection.page(3).records.include?(Recording.all[26])
+    assert_equal 20, recordset.page(3).records.size
+    assert recordset.page(3).records.include?(Recording.all[26])
 
-    assert_equal 20, collection.page(4).records.size
-    assert collection.page(4).records.include?(Recording.all[46])
+    assert_equal 20, recordset.page(4).records.size
+    assert recordset.page(4).records.include?(Recording.all[46])
   end
 
   test "page count" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: geared_pagination
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
 platform: ruby
 authors:
 - David Heinemeier Hansson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-30 00:00:00.000000000 Z
+date: 2017-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -72,6 +72,7 @@ files:
 - lib/geared_pagination/railtie.rb
 - lib/geared_pagination/ratios.rb
 - lib/geared_pagination/recordset.rb
+- test/controller_test.rb
 - test/headers_test.rb
 - test/page_test.rb
 - test/portion_test.rb
@@ -104,6 +105,7 @@ signing_key:
 specification_version: 4
 summary: Paginate Active Record sets at variable speeds
 test_files:
+- test/controller_test.rb
 - test/headers_test.rb
 - test/page_test.rb
 - test/portion_test.rb