api-pagination 1.1.1 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 09a9dd73ccebd7280dbb49978e11f0f667f178b4
-  data.tar.gz: dd0ee8715806ce59a197e76ab9e3fdec7a189634
+  metadata.gz: 39ada68101786c8ae919218460cd300a41c03dab
+  data.tar.gz: e738863fb5ca287442afa734d7b87a01c0173e86
 SHA512:
-  metadata.gz: df67ca42a6de5f48e9c38b72981ecb6ea78a4cadeeff295811c229ded4e9180633c77133d0d28aebf8bbeb5834afdbe28d42f2c273e624a854ba63f7ecf48bfd
-  data.tar.gz: f836023f6066bb9b3269924e0af441d77881ee1c7448ae5063c293ada7a6d47b843ab5339a61c4b8a70279fc9f59db42195e3b727cc54d7038e6672c7cbdecef
+  metadata.gz: 332904cbbbcb0bbfee70edab279f0aecb400d8c3d4e8b76db5ecbec51ff532132467060b5b8a238436c846ab8b4f48b5927eb8575bf1878cc31e74227a8bcb0f
+  data.tar.gz: 3d9bad3a6aff7918d9f104abb8fa351566c7d8c745afe0178d0bb1afed61a611bb95a01c7bb7abef07687ec82b747421d2e663ca1aa7e615e3b3aab9ce8793c7

data/lib/api-pagination.rb

@@ -1,37 +1,39 @@
+require 'api-pagination/hooks'
 require 'api-pagination/version'
 
 module ApiPagination
-  protected
-    def paginate(scope)
-      scope = instance_variable_get(:"@#{scope}")
-      url   = request.original_url.sub(/\?.*$/, '')
-      pages = {}
+  class << self
+    attr_writer :kaminari
+    attr_writer :will_paginate
 
-      unless scope.first_page?
-        pages[:first] = 1
-        pages[:prev]  = scope.current_page - 1
-      end
+    def kaminari?() !!@kaminari end
+    def will_paginate?() !!@will_paginate end
 
-      unless scope.last_page?
-        pages[:last] = scope.total_pages
-        pages[:next] = scope.current_page + 1
-      end
+    def paginate(collection, options = {}, &block)
+      options[:page]     ||= 1
+      options[:per_page] ||= 10
 
-      links = pages.map do |k, v|
-        new_params = request.query_parameters.merge({ :page => v })
-        %(<#{url}?#{new_params.to_param}>; rel="#{k}")
+      if ApiPagination.kaminari?
+        collection.page(options[:page]).per(options[:per_page]).tap(&block)
+      elsif ApiPagination.will_paginate?
+        collection.paginate(:page => options[:page], :per_page => options[:per_page]).tap(&block)
       end
-
-      headers['Link'] = links.join(', ') unless links.empty?
     end
-end
 
-ActionController::Base.send(:include, ApiPagination) if defined?(ActionController::Base)
-ActionController::API.send(:include, ApiPagination)  if defined?(ActionController::API)
+    def pages_from(collection)
+      {}.tap do |pages|
+        unless collection.first_page?
+          pages[:first] = 1
+          pages[:prev]  = collection.current_page - 1
+        end
 
-if defined?(WillPaginate::CollectionMethods)
-  WillPaginate::CollectionMethods.module_eval do
-    def first_page?() !previous_page end
-    def last_page?() !next_page end
+        unless collection.last_page?
+          pages[:last] = collection.total_pages
+          pages[:next] = collection.current_page + 1
+        end
+      end
+    end
   end
 end
+
+ApiPagination::Hooks.init

data/lib/api-pagination/hooks.rb

@@ -0,0 +1,47 @@
+module ApiPagination
+  class Hooks
+    def self.init
+      begin; require 'rails'; rescue LoadError; end
+      if defined?(ActionController::Base)
+        require 'rails/pagination'
+        ActionController::Base.send(:include, Rails::Pagination)
+      end
+
+      begin; require 'rails-api'; rescue LoadError; end
+      if defined?(ActionController::API)
+        require 'rails/pagination'
+        ActionController::API.send(:include, Rails::Pagination)
+      end
+
+      begin; require 'grape'; rescue LoadError; end
+      if defined?(Grape::API)
+        require 'grape/pagination'
+        Grape::API.send(:include, Grape::Pagination)
+      end
+
+      begin; require 'will_paginate'; rescue LoadError; end
+      if defined?(WillPaginate::CollectionMethods)
+        WillPaginate::CollectionMethods.module_eval do
+          def first_page?() !previous_page end
+          def last_page?() !next_page end
+        end
+
+        ApiPagination.will_paginate = true
+      end
+
+      begin; require 'kaminari'; rescue LoadError; end
+      if defined?(Kaminari)
+        ApiPagination.kaminari = true
+      end
+
+      STDERR.puts <<-EOC unless defined?(Kaminari) || defined?(WillPaginate)
+Warning: api-pagination relies on either Kaminari or WillPaginate. Please
+install either dependency by adding one of the following to your Gemfile:
+
+gem 'kaminari'
+gem 'will_paginate'
+
+EOC
+    end
+  end
+end

data/lib/api-pagination/version.rb

@@ -1,6 +1,6 @@
 module ApiPagination
-  MAJOR = 1
-  MINOR = 1
+  MAJOR = 2
+  MINOR = 0
   PATCH = 1
 
   VERSION = [MAJOR, MINOR, PATCH].join('.')

data/lib/grape/pagination.rb

@@ -0,0 +1,37 @@
+module Grape
+  module Pagination
+    def self.included(base)
+      Grape::Endpoint.class_eval do
+        def paginate(collection)
+          block = Proc.new do |collection|
+            links = (header['Link'] || "").split(',').map(&:strip)
+            url   = request.url.sub(/\?.*$/, '')
+            pages = ApiPagination.pages_from(collection)
+
+            pages.each do |k, v|
+              old_params = Rack::Utils.parse_query(request.query_string)
+              new_params = old_params.merge('page' => v)
+              links << %(<#{url}?#{new_params.to_param}>; rel="#{k}")
+            end
+
+            header 'Link', links.join(', ') unless links.empty?
+          end
+
+          ApiPagination.paginate(collection, params, &block)
+        end
+      end
+
+      base.class_eval do
+        def self.paginate(options = {})
+          options.reverse_merge!(:per_page => 10)
+          params do
+            optional :page,     :type => Integer, :default => 1,
+                                :desc => 'Page of results to fetch.'
+            optional :per_page, :type => Integer, :default => options[:per_page],
+                                :desc => 'Number of results to return per page.'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rails/pagination.rb

@@ -0,0 +1,24 @@
+module Rails
+  module Pagination
+    protected
+
+      def paginate(collection)
+        collection = instance_variable_get(:"@#{collection}")
+
+        block = Proc.new do |collection|
+          links = (headers['Link'] || "").split(',').map(&:strip)
+          url   = request.original_url.sub(/\?.*$/, '')
+          pages = ApiPagination.pages_from(collection)
+
+          pages.each do |k, v|
+            new_params = request.query_parameters.merge(:page => v)
+            links << %(<#{url}?#{new_params.to_param}>; rel="#{k}")
+          end
+
+          headers['Link'] = links.join(', ') unless links.empty?
+        end
+
+        ApiPagination.paginate(collection, params, &block)
+      end
+  end
+end

data/spec/grape_spec.rb

@@ -0,0 +1,44 @@
+require 'spec_helper'
+require 'support/shared_examples/existing_headers'
+require 'support/shared_examples/first_page'
+require 'support/shared_examples/middle_page'
+require 'support/shared_examples/last_page'
+
+describe NumbersAPI do
+  describe 'GET #index' do
+    let(:links) { last_response.headers['Link'].split(', ') }
+
+    context 'without enough items to give more than one page' do
+      it 'should not paginate' do
+        get :numbers, :count => 20
+        expect(last_response.headers.keys).not_to include('Link')
+      end
+    end
+
+    context 'with existing Link headers' do
+      before { get :numbers, :count => 30, :with_headers => true }
+
+      it_behaves_like 'an endpoint with existing Link headers'
+    end
+
+    context 'with enough items to paginate' do
+      context 'when on the first page' do
+        before { get :numbers, :count => 100 }
+
+        it_behaves_like 'an endpoint with a first page'
+      end
+
+      context 'when on the last page' do
+        before { get :numbers, :count => 100, :page => 4 }
+
+        it_behaves_like 'an endpoint with a last page'
+      end
+
+      context 'when somewhere comfortably in the middle' do
+        before { get :numbers, :count => 100, :page => 2 }
+
+        it_behaves_like 'an endpoint with a middle page'
+      end
+    end
+  end
+end

data/spec/rails_spec.rb

@@ -0,0 +1,50 @@
+require 'spec_helper'
+require 'support/shared_examples/existing_headers'
+require 'support/shared_examples/first_page'
+require 'support/shared_examples/middle_page'
+require 'support/shared_examples/last_page'
+
+describe NumbersController, :type => :controller do
+  before { request.host = 'example.org' }
+  describe 'GET #index' do
+    let(:links) { response.headers['Link'].split(', ') }
+
+    context 'without enough items to give more than one page' do
+      it 'should not paginate' do
+        get :index, :count => 20
+        expect(response.headers.keys).not_to include('Link')
+      end
+    end
+
+    context 'with existing Link headers' do
+      before { get :index, :count => 30, :with_headers => true }
+
+      it_behaves_like 'an endpoint with existing Link headers'
+    end
+
+    context 'with enough items to paginate' do
+      context 'when on the first page' do
+        before { get :index, :count => 100 }
+
+        it_behaves_like 'an endpoint with a first page'
+      end
+
+      context 'when on the last page' do
+        before { get :index, :count => 100, :page => 4 }
+
+        it_behaves_like 'an endpoint with a last page'
+      end
+
+      context 'when somewhere comfortably in the middle' do
+        before { get :index, :count => 100, :page => 2 }
+
+        it_behaves_like 'an endpoint with a middle page'
+      end
+    end
+  end
+end
+
+
+
+
+

data/spec/spec_helper.rb

@@ -1,49 +1,42 @@
-require 'action_controller'
+require 'support/numbers_controller'
+require 'support/numbers_api'
 require 'api-pagination'
-require 'rspec/autorun'
-require 'ostruct'
-
-module Rails
-  def self.application
-    @application ||= begin
-      routes = ActionDispatch::Routing::RouteSet.new
-      OpenStruct.new(routes: routes, env_config: {})
-    end
+
+# Quacks like Kaminari and will_paginate
+PaginatedSet = Struct.new(:current_page, :per_page, :total_count) do
+  def total_pages
+    total_count.zero? ? 1 : (total_count.to_f / per_page).ceil
   end
-end
 
-module ControllerExampleGroup
-  def self.included(base)
-    base.extend ClassMethods
-    base.send(:include, ActionController::TestCase::Behavior)
+  def first_page?() current_page == 1 end
+  def last_page?() current_page == total_pages end
 
-    base.prepend_before do
-      @routes = Rails.application.routes
-      @controller = described_class.new
-    end
+  def page(page)
+    current_page = page
+    self
   end
 
-  module ClassMethods
-    def setup(*methods)
-      methods.each do |method|
-        if method.to_s =~ /^setup_(fixtures|controller_request_and_response)$/
-          prepend_before { send method }
-        else
-          before         { send method }
-        end
-      end
-    end
-
-    def teardown(*methods)
-      methods.each { |method| after { send method } }
-    end
+  def per(per)
+    per_page = per
+    self
+  end
+
+  def paginate(options = {})
+    page(options[:page]).per(options[:per_page])
   end
 end
 
+ApiPagination.kaminari      = ENV['PAGINATOR'] == 'kaminari'
+ApiPagination.will_paginate = ENV['PAGINATOR'] == 'will_paginate'
+
 RSpec.configure do |config|
-  config.treat_symbols_as_metadata_keys_with_true_values = true
-  config.run_all_when_everything_filtered = true
-  config.filter_run :focus
+  config.include Rack::Test::Methods
+  config.include ControllerExampleGroup, :type => :controller
+
+  # Disable the 'should' syntax.
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
 
   # Run specs in random order to surface order dependencies. If you find an
   # order dependency and want to debug it, you can fix the order by providing
@@ -51,5 +44,7 @@ RSpec.configure do |config|
   #     --seed 1234
   config.order = 'random'
 
-  config.include ControllerExampleGroup, :type => :controller
+  def app
+    NumbersAPI
+  end
 end

data/spec/support/numbers_api.rb

@@ -0,0 +1,23 @@
+require 'grape'
+require 'api-pagination'
+
+class NumbersAPI < Grape::API
+  format :json
+
+  desc 'Return some paginated set of numbers'
+  paginate :per_page => 25
+  params do
+    requires :count, :type => Integer
+    optional :with_headers, :default => false, :type => Boolean
+  end
+  get :numbers do
+    if params[:with_headers]
+      url   = request.url.sub(/\?.*/, '')
+      query = Rack::Utils.parse_query(request.query_string)
+      query.delete('with_headers')
+      header 'Link', %(<#{url}?#{query.to_query}>; rel="without")
+    end
+
+    paginate PaginatedSet.new(params[:page], params[:per_page], params[:count])
+  end
+end

data/spec/support/numbers_controller.rb

@@ -0,0 +1,63 @@
+require 'action_controller'
+require 'ostruct'
+
+module Rails
+  def self.application
+    @application ||= begin
+      routes = ActionDispatch::Routing::RouteSet.new
+      OpenStruct.new(:routes => routes, :env_config => {})
+    end
+  end
+end
+
+module ControllerExampleGroup
+  def self.included(base)
+    base.extend ClassMethods
+    base.send(:include, ActionController::TestCase::Behavior)
+
+    base.prepend_before do
+      @routes = Rails.application.routes
+      @controller = described_class.new
+    end
+  end
+
+  module ClassMethods
+    def setup(*methods)
+      methods.each do |method|
+        if method.to_s =~ /^setup_(fixtures|controller_request_and_response)$/
+          prepend_before { send method }
+        else
+          before         { send method }
+        end
+      end
+    end
+
+    def teardown(*methods)
+      methods.each { |method| after { send method } }
+    end
+  end
+end
+
+Rails.application.routes.draw do
+  resources :numbers, :only => [:index]
+end
+
+class NumbersController < ActionController::Base
+  include Rails.application.routes.url_helpers
+
+  after_filter :only => [:index] { paginate(:numbers) }
+
+  def index
+    page = params.fetch(:page, 1).to_i
+    total = params.fetch(:count).to_i
+
+    if params[:with_headers]
+      query = request.query_parameters.dup
+      query.delete(:with_headers)
+      headers['Link'] = %(<#{numbers_url}?#{query.to_param}>; rel="without")
+    end
+
+    @numbers = PaginatedSet.new(page, 25, total)
+    render :json => @numbers
+  end
+end