geared_pagination 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 86fef30f9fb2e850e8b305a079d05d39007ec6bd
+  data.tar.gz: 83e91624d0fbd65747604f91628e826f00a131b0
+SHA512:
+  metadata.gz: f7e00eb4a7598860c873eb1810ffdba1c8e5a30d625d42b6a7e10f035786e593724b74c8c496089495ada18c992af7b41534041e1b5951f8573932a3d533509e
+  data.tar.gz: c2feb3068a763034a474fca15cd793b3fdeae695cee4c6f0187c4ea2918a76a24f9a124061407922a3b397137119fdc234413153563ba0ed9f3301af9204238e

data/Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rake'
+gem 'byebug'

data/Gemfile.lock

@@ -0,0 +1,38 @@
+PATH
+  remote: .
+  specs:
+    geared_pagination (0.1)
+      activesupport (>= 5.0)
+      addressable (>= 2.5.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (5.1.0.beta1)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (~> 0.7)
+      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)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.12)
+  byebug
+  geared_pagination!
+  rake
+
+BUNDLED WITH
+   1.14.6

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2017 David Heinemeier Hansson, Basecamp
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,40 @@
+# 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
+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
+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.
+
+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.
+
+## Example
+
+```ruby
+class MessagesController < ApplicationController
+  def index
+    @page = current_page_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):
+
+<%= render @page.records %>
+
+<% if @page.last? %>
+  No more pages!
+<% else %> 
+  <%= link_to "Next page", messages_path(page: @page.next_number) %>
+<% end %>
+
+```
+
+## License
+Geared Pagination is released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require "bundler/setup"
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new do |test|
+  test.libs << "test"
+  test.test_files = FileList["test/*_test.rb"]
+end
+
+task default: :test

data/geared_pagination.gemspec

@@ -0,0 +1,19 @@
+Gem::Specification.new do |s|
+  s.name     = 'geared_pagination'
+  s.version  = '0.1'
+  s.authors  = 'David Heinemeier Hansson'
+  s.email    = 'david@basecamp.com'
+  s.summary  = 'Paginate Active Record sets at variable speeds'
+  s.homepage = 'https://github.com/basecamp/geared_pagination'
+  s.license  = 'MIT'
+
+  s.required_ruby_version = '>= 1.9.3'
+
+  s.add_dependency 'activesupport', '>= 5.0'
+  s.add_dependency 'addressable', '>= 2.5.0'
+
+  s.add_development_dependency 'bundler', '~> 1.12'
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- test/*`.split("\n")
+end

data/lib/geared_pagination.rb

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

data/lib/geared_pagination/controller.rb

@@ -0,0 +1,30 @@
+require 'geared_pagination/recordset'
+require 'geared_pagination/headers'
+
+module GearedPagination
+  module Controller
+    extend ActiveSupport::Concern
+
+    included do
+      after_action :set_paginated_headers
+    end
+
+    private
+      def set_page_and_extract_portion_from(records, per_page: nil)
+        @page = current_page_from(records, 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)
+      end
+
+      def set_paginated_headers
+        GearedPagination::Headers.new(page: @page, controller: self).apply if @page.is_a?(GearedPagination::Page)
+      end
+
+      def current_page_param
+        params[:page].to_i > 0 ? params[:page].to_i : 1
+      end
+  end
+end

data/lib/geared_pagination/headers.rb

@@ -0,0 +1,35 @@
+require 'addressable/uri'
+
+module GearedPagination
+  class Headers
+    def initialize(page:, controller:)
+      @page, @controller = page, controller
+    end
+
+    def apply
+      @controller.headers.update(headers) if applicable?
+    end
+
+    private
+      def headers
+        Hash.new.tap do |h|
+          h["X-Total-Count"] = @page.collection.records_count.to_s
+          h["Link"] = next_page_link_header unless @page.last?
+        end
+      end
+
+      def applicable?
+        @controller.request.format&.json?
+      end
+
+      def next_page_link_header
+        link_header(rel: :next, page_number: @page.next_number).to_s
+      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}"}
+      end
+  end
+end

data/lib/geared_pagination/page.rb

@@ -0,0 +1,43 @@
+require 'geared_pagination/portion'
+
+module GearedPagination
+  class Page
+    attr_reader :number, :collection
+
+    def initialize(number, from:)
+      @number, @collection = number, from
+      @portion = GearedPagination::Portion.new(page_number: number, per_page: from.ratios)
+    end
+
+    def records
+      @records ||= @portion.from(collection.records)
+    end
+
+
+    def used?
+      records.load.any?
+    end
+
+    def empty?
+      records.load.none?
+    end
+
+
+    def first?
+      number == 1
+    end
+
+    def only?
+      collection.page_count == 1
+    end
+
+    def last?
+      number == collection.page_count
+    end
+
+
+    def next_number
+      number + 1
+    end
+  end
+end

data/lib/geared_pagination/portion.rb

@@ -0,0 +1,23 @@
+require 'geared_pagination/ratios'
+
+module GearedPagination
+  class Portion
+    attr_reader :page_number, :ratios
+
+    def initialize(page_number: 1, per_page: GearedPagination::Ratios.new)
+      @page_number, @ratios = page_number, per_page
+    end
+
+    def from(scope)
+      scope.limit(limit).offset(offset)
+    end
+
+    def limit
+      ratios[page_number]
+    end
+
+    def offset
+      (page_number - 1).times.sum { |index| ratios[index + 1] }
+    end
+  end
+end

data/lib/geared_pagination/railtie.rb

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

data/lib/geared_pagination/ratios.rb

@@ -0,0 +1,13 @@
+module GearedPagination
+  class Ratios
+    DEFAULTS = [ 15, 30, 50, 100 ]
+
+    def initialize(ratios = nil)
+      @ratios = Array(ratios || DEFAULTS)
+    end
+
+    def [](page_number)
+      @ratios[page_number - 1] || @ratios.last
+    end
+  end
+end

data/lib/geared_pagination/recordset.rb

@@ -0,0 +1,35 @@
+require 'geared_pagination/ratios'
+require 'geared_pagination/page'
+
+module GearedPagination
+  class Recordset
+    attr_reader :records, :ratios
+
+    def initialize(records, per_page: nil)
+      @records = records
+      @ratios  = GearedPagination::Ratios.new(per_page)
+    end
+
+    def page(number)
+      GearedPagination::Page.new(number, from: self)
+    end
+
+    def page_count
+      @page_count ||= begin
+        count    = 0
+        residual = records_count
+
+        while residual > 0
+          count   += 1
+          residual = residual - ratios[count]
+        end
+
+        count
+      end
+    end
+
+    def records_count
+      @records_count ||= records.unscope(:limit).unscope(:offset).count
+    end
+  end
+end

data/test/headers_test.rb

@@ -0,0 +1,47 @@
+require 'test_helper'
+require 'active_support/core_ext/string/inquiry'
+require 'geared_pagination/headers'
+require 'geared_pagination/recordset'
+
+class GearedPagination::HeadersTest < ActiveSupport::TestCase
+  Request    = Struct.new(:url, :format)
+  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), {})
+
+    @single_page_collection = GearedPagination::Recordset.new(Recording.all, per_page: 1000) 
+    @many_page_collection   = 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
+    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
+    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
+    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"',
+      @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"',
+      @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
+    assert @controller_serving_json.headers["Link"].nil?
+  end
+end

data/test/page_test.rb

@@ -0,0 +1,23 @@
+require 'test_helper'
+require 'geared_pagination/recordset'
+
+class GearedPagination::PageTest < ActiveSupport::TestCase
+  test "first" do
+    assert GearedPagination::Recordset.new(Recording.all).page(1).first?
+    assert_not GearedPagination::Recordset.new(Recording.all).page(2).first?
+  end
+
+  test "only" do
+    assert     GearedPagination::Recordset.new(Recording.all, per_page: 1000).page(1).only?
+    assert_not GearedPagination::Recordset.new(Recording.all, per_page:    1).page(1).only?
+  end
+
+  test "last" do
+    assert     GearedPagination::Recordset.new(Recording.all, per_page: 1000).page(1).last?
+    assert_not GearedPagination::Recordset.new(Recording.all, per_page:    1).page(1).last?
+  end
+
+  test "next_number" do
+    assert_equal 2, GearedPagination::Recordset.new(Recording.all, per_page: 1000).page(1).next_number
+  end
+end

data/test/portion_test.rb

@@ -0,0 +1,16 @@
+require 'test_helper'
+require 'active_support/core_ext/array/access'
+require 'geared_pagination/portion'
+
+class GearedPagination::PortionTest < ActiveSupport::TestCase
+  test "offset" do
+    assert_equal 0, GearedPagination::Portion.new(page_number: 1).offset
+    assert_equal GearedPagination::Ratios::DEFAULTS.first, GearedPagination::Portion.new(page_number: 2).offset
+    assert_equal GearedPagination::Ratios::DEFAULTS.first + GearedPagination::Ratios::DEFAULTS.second, GearedPagination::Portion.new(page_number: 3).offset
+  end
+
+  test "limit" do
+    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
+end

data/test/ratios_test.rb

@@ -0,0 +1,27 @@
+require 'test_helper'
+require 'geared_pagination/ratios'
+
+class GearedPagination::RatiosTest < ActiveSupport::TestCase
+  test "single limit" do
+    limits = GearedPagination::Ratios.new(10)
+
+    assert_equal 10, limits[1]
+    assert_equal 10, limits[2]
+  end
+
+  test "range of limits" do
+    limits = GearedPagination::Ratios.new([ 10, 25, 100 ])
+
+    assert_equal 10, limits[1]
+    assert_equal 25, limits[2]
+    assert_equal 100, limits[3]
+    assert_equal 100, limits[4]
+  end
+
+  test "default limits" do
+    limits = GearedPagination::Ratios.new
+
+    assert_equal GearedPagination::Ratios::DEFAULTS.first, limits[1]
+    assert_equal GearedPagination::Ratios::DEFAULTS.last, limits[99]
+  end
+end

data/test/recording_stubs.rb

@@ -0,0 +1,62 @@
+class Recordings
+  def initialize(recordings)
+    @recordings = recordings
+    @offset = 0
+    @limit = nil
+  end
+
+  def limit(size)
+    @limit = size
+    self
+  end
+
+  def offset(number)
+    @offset = number
+    self
+  end
+
+  def unscope(restriction)
+    case restriction
+    when :offset then @offset = 0
+    when :limit  then @limit  = nil
+    end
+
+    self
+  end
+
+
+  def [](index)
+    slice[index]
+  end
+
+  def count
+    slice.size
+  end
+  alias :size :count
+
+  def include?(record)
+    slice.include?(record)
+  end
+
+
+  private
+    def slice
+      @recordings[@offset..(@limit ? @offset + (@limit - 1) : -1)]
+    end
+end
+
+class Recording
+  def self.all(count = 120)
+    Recordings.new(count.times.collect { |i| new(i) })
+  end
+
+  attr_reader :number
+
+  def initialize(number)
+    @number = 1
+  end
+
+  def ==(comparison)
+    @number == comparison.number
+  end
+end

data/test/recordset_test.rb

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

data/test/test_helper.rb

@@ -0,0 +1,5 @@
+require 'bundler/setup'
+require 'active_support'
+require 'active_support/testing/autorun'
+require 'byebug'
+require 'recording_stubs'

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: geared_pagination
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- David Heinemeier Hansson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-03-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: addressable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.5.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.12'
+description: 
+email: david@basecamp.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- Gemfile.lock
+- MIT-LICENSE
+- README.md
+- Rakefile
+- geared_pagination.gemspec
+- lib/geared_pagination.rb
+- lib/geared_pagination/controller.rb
+- lib/geared_pagination/headers.rb
+- lib/geared_pagination/page.rb
+- lib/geared_pagination/portion.rb
+- lib/geared_pagination/railtie.rb
+- lib/geared_pagination/ratios.rb
+- lib/geared_pagination/recordset.rb
+- test/headers_test.rb
+- test/page_test.rb
+- test/portion_test.rb
+- test/ratios_test.rb
+- test/recording_stubs.rb
+- test/recordset_test.rb
+- test/test_helper.rb
+homepage: https://github.com/basecamp/geared_pagination
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.3
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.8
+signing_key: 
+specification_version: 4
+summary: Paginate Active Record sets at variable speeds
+test_files:
+- test/headers_test.rb
+- test/page_test.rb
+- test/portion_test.rb
+- test/ratios_test.rb
+- test/recording_stubs.rb
+- test/recordset_test.rb
+- test/test_helper.rb