api-pagination 3.1.0 → 3.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2c576834fa7e045c8227f8ac9eb178dedc241533
-  data.tar.gz: 6c620fe958d4b4c87e8df6d28faf4a24c500e2e4
+  metadata.gz: c9b48cddb3e2509595aa30dd7c836cde57a4a690
+  data.tar.gz: 3fc62e5440d43d007d4b54d415be8e6f0011dd3d
 SHA512:
-  metadata.gz: b22e56913a84c875f177f1e3acb401bcb4decf175ed31023efe6cfdc33782d7d67e1b84e85cf8f0a9454181aa2284047d24c0f8c43b9b7328266c8e28500beaf
-  data.tar.gz: c23680b6346a5dab04bbecfd6a18ec4d54190f2907b488936743108eaf4657b66d02724ab64feab558f731ca80e1287784c3fa2c7e7634df163e44b167a3c38a
+  metadata.gz: 5d74a30037b8433a10c00e127cdded4ff3c60164a1beb45ea5c66d8532cb2ed43971e73f6a32d5e886f09fa0a10d6f8013d79a1e067a44acf5746a57fcdd7744
+  data.tar.gz: da3767bee2071943af66c7bc424d0a4b31504fc03d8d8109b08968adc8e7c6389a6f6f0f26de874a62961c1cb473aad3c5a24dcfab997f2fef1b42cc9981ebc1

data/lib/api-pagination.rb

@@ -1,24 +1,20 @@
-require 'api-pagination/hooks'
+require 'api-pagination/configuration'
 require 'api-pagination/version'
 
 module ApiPagination
   class << self
-    attr_reader :paginator
-
     def paginate(collection, options = {})
-      options[:page]     ||= 1
-      options[:per_page] = (options[:per_page].to_i <= 0 ? 25 : options[:per_page])
+      options[:page]     = options[:page].to_i
+      options[:page]     = 1 if options[:page] <= 0
+      options[:per_page] = options[:per_page].to_i
 
-      case ApiPagination.paginator
+      case ApiPagination.config.paginator
       when :kaminari
-        collection = Kaminari.paginate_array(collection) if collection.is_a?(Array)
-        collection.page(options[:page]).per(options[:per_page])
+        paginate_with_kaminari(collection, options)
       when :will_paginate
-        if defined?(Sequel::Dataset) && collection.kind_of?(Sequel::Dataset)
-          collection.paginate(options[:page], options[:per_page])
-        else
-          collection.paginate(:page => options[:page], :per_page => options[:per_page])
-        end
+        paginate_with_will_paginate(collection, options)
+      else
+        raise StandardError, "Unknown paginator: #{ApiPagination.config.paginator}"
       end
     end
 
@@ -37,10 +33,50 @@ module ApiPagination
     end
 
     def total_from(collection)
-      case ApiPagination.paginator
+      case ApiPagination.config.paginator
         when :kaminari      then collection.total_count.to_s
         when :will_paginate then collection.total_entries.to_s
       end
     end
+
+    def paginator
+      warn "[DEPRECATION] ApiPagination.paginator is deprecated. Please use ApiPagination.config.paginator"
+      config.paginator
+    end
+
+    def per_page_header
+      warn "[DEPRECATION] ApiPagination.paginator is deprecated. Please use ApiPagination.config.per_page_header"
+      config.per_page_header
+    end
+
+    def total_header
+      warn "[DEPRECATION] ApiPagination.paginator is deprecated. Please use ApiPagination.config.total_header"
+      config.total_header
+    end
+
+    private
+
+    def paginate_with_kaminari(collection, options)
+      if Kaminari.config.max_per_page && options[:per_page] > Kaminari.config.max_per_page
+        options[:per_page] = Kaminari.config.max_per_page
+      elsif options[:per_page] <= 0
+        options[:per_page] = Kaminari.config.default_per_page
+      end
+
+      collection = Kaminari.paginate_array(collection) if collection.is_a?(Array)
+      collection.page(options[:page]).per(options[:per_page])
+    end
+
+    def paginate_with_will_paginate(collection, options)
+      options[:per_page] = WillPaginate.per_page if options[:per_page] <= 0
+
+      if defined?(Sequel::Dataset) && collection.kind_of?(Sequel::Dataset)
+        collection.paginate(options[:page], options[:per_page])
+      else
+        collection.paginate(:page => options[:page], :per_page => options[:per_page])
+      end
+    end
   end
 end
+
+require 'api-pagination/hooks'

data/lib/api-pagination/configuration.rb

@@ -0,0 +1,97 @@
+module ApiPagination
+  class Configuration
+    attr_reader :paginator
+
+    attr_accessor :total_header
+
+    attr_accessor :per_page_header
+
+    def configure(&block)
+      yield self
+    end
+
+    def initialize
+      @total_header    = 'Total'
+      @per_page_header = 'Per-Page'
+      set_paginator
+    end
+
+    def paginator=(paginator)
+      case paginator
+      when :kaminari
+        use_kaminari
+      when :will_paginate
+        use_will_paginate
+      else
+        raise StandardError, "Unknown paginator: #{paginator}"
+      end
+    end
+
+    private
+
+    def set_paginator
+      if defined?(Kaminari) && defined?(WillPaginate::CollectionMethods)
+        Kernel.warn <<-WARNING
+Warning: api-pagination relies on either Kaminari or WillPaginate, but both are
+currently active. If possible, you should remove one or the other. If you can't,
+you must configure api-pagination on your own. For example:
+
+ApiPagination.configure do |config|
+  config.paginator = Kaminari
+end
+
+WARNING
+      elsif defined?(Kaminari)
+        use_kaminari and return
+      elsif defined?(WillPaginate::CollectionMethods)
+        use_will_paginate and return
+      end
+
+      begin
+        require 'kaminari'
+        use_kaminari and return
+      rescue LoadError
+      end
+
+      begin
+        require 'will_paginate'
+        use_will_paginate and return
+      rescue LoadError
+      end
+
+      Kernel.warn <<-WARNING
+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'
+
+WARNING
+    end
+
+    def use_kaminari
+      require 'kaminari/models/array_extension'
+      @paginator = :kaminari
+    end
+
+    def use_will_paginate
+      WillPaginate::CollectionMethods.module_eval do
+        def first_page?() !previous_page end
+        def last_page?() !next_page end
+      end
+
+      @paginator = :will_paginate
+    end
+  end
+
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+    alias :configuration :config
+  end
+end

data/lib/api-pagination/hooks.rb

@@ -1,49 +1,17 @@
-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.instance_variable_set(:@paginator, :will_paginate)
-      end
-
-      begin; require 'kaminari'; rescue LoadError; end
-      if defined?(Kaminari)
-        ApiPagination.instance_variable_set(:@paginator, :kaminari)
-      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'
+begin; require 'rails'; rescue LoadError; end
+if defined?(ActionController::Base)
+  require 'rails/pagination'
+  ActionController::Base.send(:include, Rails::Pagination)
+end
 
-EOC
-    end
-  end
+begin; require 'rails-api'; rescue LoadError; end
+if defined?(ActionController::API)
+  require 'rails/pagination'
+  ActionController::API.send(:include, Rails::Pagination)
 end
 
-ApiPagination::Hooks.init
+begin; require 'grape'; rescue LoadError; end
+if defined?(Grape::API)
+  require 'grape/pagination'
+  Grape::API.send(:include, Grape::Pagination)
+end

data/lib/api-pagination/version.rb

@@ -1,7 +1,7 @@
 module ApiPagination
   class Version
     MAJOR = 3
-    MINOR = 1
+    MINOR = 2
     PATCH = 0
 
     def self.to_s

data/lib/grape/pagination.rb

@@ -3,9 +3,10 @@ module Grape
     def self.included(base)
       Grape::Endpoint.class_eval do
         def paginate(collection)
+          per_page = params[:per_page] || route_setting(:per_page)
           options = {
             :page     => params[:page],
-            :per_page => (params[:per_page] || settings[:per_page])
+            :per_page => [per_page, route_setting(:max_per_page)].compact.min
           }
           collection = ApiPagination.paginate(collection, options)
 
@@ -19,8 +20,12 @@ module Grape
             links << %(<#{url}?#{new_params.to_param}>; rel="#{k}")
           end
 
-          header 'Link', links.join(', ') unless links.empty?
-          header 'Total', ApiPagination.total_from(collection)
+          total_header    = ApiPagination.config.total_header
+          per_page_header = ApiPagination.config.per_page_header
+
+          header 'Link',          links.join(', ') unless links.empty?
+          header total_header,    ApiPagination.total_from(collection)
+          header per_page_header, options[:per_page].to_s
 
           return collection
         end
@@ -28,7 +33,8 @@ module Grape
 
       base.class_eval do
         def self.paginate(options = {})
-          set :per_page, (options[:per_page] || 25)
+          route_setting :per_page, (options[:per_page] || 25)
+          route_setting :max_per_page, options[:max_per_page]
           params do
             optional :page,     :type => Integer, :default => 1,
                                 :desc => 'Page of results to fetch.'

data/lib/rails/pagination.rb

@@ -39,11 +39,14 @@ module Rails
         links << %(<#{url}?#{new_params.to_param}>; rel="#{k}")
       end
 
-      headers['Link']  = links.join(', ') unless links.empty?
-      headers['Total'] = ApiPagination.total_from(collection)
+      total_header    = ApiPagination.config.total_header
+      per_page_header = ApiPagination.config.per_page_header
+
+      headers['Link']          = links.join(', ') unless links.empty?
+      headers[total_header]    = ApiPagination.total_from(collection)
+      headers[per_page_header] = options[:per_page].to_s
 
       return collection
     end
   end
 end
-

data/spec/grape_spec.rb

@@ -8,9 +8,10 @@ describe NumbersAPI do
   describe 'GET #index' do
     let(:links) { last_response.headers['Link'].split(', ') }
     let(:total) { last_response.headers['Total'].to_i }
+    let(:per_page) { last_response.headers['Per-Page'].to_i }
 
     context 'without enough items to give more than one page' do
-      before { get :numbers, :count => 10 }
+      before { get '/numbers', :count => 10 }
 
       it 'should not paginate' do
         expect(last_response.headers.keys).not_to include('Link')
@@ -20,6 +21,10 @@ describe NumbersAPI do
         expect(total).to eq(10)
       end
 
+      it 'should give a Per-Page header' do
+        expect(per_page).to eq(10)
+      end
+
       it 'should list all numbers in the response body' do
         body = '[1,2,3,4,5,6,7,8,9,10]'
         expect(last_response.body).to eq(body)
@@ -27,29 +32,72 @@ describe NumbersAPI do
     end
 
     context 'with existing Link headers' do
-      before { get :numbers, :count => 30, :with_headers => true }
+      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 }
+        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 => 10 }
+        before { get '/numbers', :count => 100, :page => 10 }
 
         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 }
+        before { get '/numbers', :count => 100, :page => 2 }
 
         it_behaves_like 'an endpoint with a middle page'
       end
+
+      context 'with a max_per_page setting' do
+        before { get '/numbers', :count => 100, :per_page => 30 }
+
+        it 'should not go above the max_per_page_limit' do
+          body = '[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25]'
+
+          expect(last_response.body).to eq(body)
+        end
+      end
+    end
+
+    context 'with custom response headers' do
+      before do
+        ApiPagination.config.total_header    = 'X-Total-Count'
+        ApiPagination.config.per_page_header = 'X-Per-Page'
+
+        get '/numbers', count: 10
+      end
+
+      after do
+        ApiPagination.config.total_header    = 'Total'
+        ApiPagination.config.per_page_header = 'Per-Page'
+      end
+
+      let(:total) { last_response.header['X-Total-Count'].to_i }
+      let(:per_page) { last_response.header['X-Per-Page'].to_i }
+
+      it 'should give a X-Total-Count header' do
+        headers_keys = last_response.headers.keys
+
+        expect(headers_keys).not_to include('Total')
+        expect(headers_keys).to include('X-Total-Count')
+        expect(total).to eq(10)
+      end
+
+      it 'should give a X-Per-Page header' do
+        headers_keys = last_response.headers.keys
+
+        expect(headers_keys).not_to include('Per-Page')
+        expect(headers_keys).to include('X-Per-Page')
+        expect(per_page).to eq(10)
+      end
     end
   end
 end

data/spec/rails_spec.rb

@@ -10,6 +10,7 @@ describe NumbersController, :type => :controller do
   describe 'GET #index' do
     let(:links) { response.headers['Link'].split(', ') }
     let(:total) { response.headers['Total'].to_i }
+    let(:per_page) { response.headers['Per-Page'].to_i }
 
     context 'without enough items to give more than one page' do
       before { get :index, :count => 10 }
@@ -22,6 +23,10 @@ describe NumbersController, :type => :controller do
         expect(total).to eq(10)
       end
 
+      it 'should give a Per-Page header' do
+        expect(per_page).to eq(10)
+      end
+
       it 'should list all numbers in the response body' do
         body = '[1,2,3,4,5,6,7,8,9,10]'
         expect(response.body).to eq(body)
@@ -63,10 +68,38 @@ describe NumbersController, :type => :controller do
         expect(response.body).to eq(json)
       end
     end
-  end
-end
 
+    context 'with custom response headers' do
+      before do
+        ApiPagination.config.total_header    = 'X-Total-Count'
+        ApiPagination.config.per_page_header = 'X-Per-Page'
 
+        get :index, count: 10
+      end
+
+      after do
+        ApiPagination.config.total_header    = 'Total'
+        ApiPagination.config.per_page_header = 'Per-Page'
+      end
 
+      let(:total) { response.header['X-Total-Count'].to_i }
+      let(:per_page) { response.header['X-Per-Page'].to_i }
 
+      it 'should give a X-Total-Count header' do
+        headers_keys = response.headers.keys
 
+        expect(headers_keys).not_to include('Total')
+        expect(headers_keys).to include('X-Total-Count')
+        expect(total).to eq(10)
+      end
+
+      it 'should give a X-Per-Page header' do
+        headers_keys = response.headers.keys
+
+        expect(headers_keys).not_to include('Per-Page')
+        expect(headers_keys).to include('X-Per-Page')
+        expect(per_page).to eq(10)
+      end
+    end
+  end
+end

data/spec/sequel_spec.rb

@@ -1,6 +1,6 @@
 require 'spec_helper'
 
-if ApiPagination.paginator == :will_paginate
+if ApiPagination.config.paginator == :will_paginate
   require 'sqlite3'
   require 'sequel'
   require 'will_paginate/sequel'

data/spec/spec_helper.rb

@@ -3,17 +3,15 @@ require 'support/numbers_api'
 require 'api-pagination'
 
 if ENV['PAGINATOR']
-  ApiPagination.instance_variable_set(:@paginator, ENV['PAGINATOR'].to_sym)
+  require ENV['PAGINATOR']
+  ApiPagination.config.paginator = ENV['PAGINATOR'].to_sym
 else
   warn 'No PAGINATOR set. Defaulting to kaminari. To test against will_paginate, run `PAGINATOR=will_paginate bundle exec rspec`'
-  ApiPagination.instance_variable_set(:@paginator, :kaminari)
+  require 'kaminari'
+  ApiPagination.config.paginator = :kaminari
 end
 
-if ApiPagination.paginator == :kaminari
-  Kaminari::Hooks.init
-elsif ApiPagination.paginator == :will_paginate
-  require 'will_paginate/array'
-end
+require 'will_paginate/array'
 
 RSpec.configure do |config|
   config.include Rack::Test::Methods

data/spec/support/numbers_api.rb

@@ -5,7 +5,7 @@ class NumbersAPI < Grape::API
   format :json
 
   desc 'Return some paginated set of numbers'
-  paginate :per_page => 10
+  paginate :per_page => 10, :max_per_page => 25 
   params do
     requires :count, :type => Integer
     optional :with_headers, :default => false, :type => Boolean

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: api-pagination
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.2.0
 platform: ruby
 authors:
 - David Celis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-21 00:00:00.000000000 Z
+date: 2015-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -30,14 +30,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.10.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
@@ -88,6 +88,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - lib/api-pagination.rb
+- lib/api-pagination/configuration.rb
 - lib/api-pagination/hooks.rb
 - lib/api-pagination/version.rb
 - lib/grape/pagination.rb
@@ -122,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: Link header pagination for Rails and Grape APIs. Don't use the request body.
@@ -137,3 +138,4 @@ test_files:
 - spec/support/shared_examples/first_page.rb
 - spec/support/shared_examples/last_page.rb
 - spec/support/shared_examples/middle_page.rb
+has_rdoc: