api-pagination 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 44223a7f3dfd7705282d1c93abc09c04e55b5cd0
-  data.tar.gz: dbcb589c144ae07bc298b90da5de60eb627b021c
+  metadata.gz: 1c24620f87870aa113532b4e5b68ac39d48196a8
+  data.tar.gz: c5b6ebc23e6db9248dcedfa86ae6def3ddd91b0f
 SHA512:
-  metadata.gz: fe8b5fb947b1bf135a49283f4ca86f3b3c5131b564c2492105f358f5864eabf6f0509f5d54594c94e8dfff9a1f2a02fe4573c23dcd32625d08a2978b7be41bc8
-  data.tar.gz: df50ee727c766cb82b2f23efeae78f1c91ea63aa790e0459f5645ccaf48c52145904896592ec596990b8c40a4b542530613f4cc0e151b0dbee500254d06a4b72
+  metadata.gz: fe232ed61e1987363a1da75f58480f1f5d0485364180c08b9a3ce3ebf5079a1ec34c5448b43e2e94b019b29a72b820539371274cefde5835e96476204c9c3e70
+  data.tar.gz: 33bbf495e991be605c548d6f20c804a79339f1a45ec47eca36c469fb544389e6918daa7f9eb9fb9cfb8ef567a6be2945379b1168cfe46d780f499fb7a61e69ac

data/lib/api-pagination.rb

@@ -1,33 +1,20 @@
+require 'api-pagination/configuration'
 require 'api-pagination/version'
 
 module ApiPagination
   class << self
-    attr_reader :paginator
-
     def paginate(collection, options = {})
       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
-        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])
+        paginate_with_kaminari(collection, options)
       when :will_paginate
-        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
+        paginate_with_will_paginate(collection, options)
       else
-        raise StandardError, "Unknown paginator: #{ApiPagination.paginator}"
+        raise StandardError, "Unknown paginator: #{ApiPagination.config.paginator}"
       end
     end
 
@@ -46,11 +33,49 @@ 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
 

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,77 +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
-
-      # Kaminari and will_paginate conflict with each other, so we should check
-      # to see if either is already active before attempting to load them.
-      if defined?(Kaminari) && defined?(WillPaginate::CollectionMethods)
-        STDERR.puts <<-EOC
-Warning: api-pagination relies on either Kaminari or WillPaginate, but these
-gems conflict.  Please ensure only one of them is active at any given time.
-
-EOC
-        return
-      elsif defined?(Kaminari)
-        initialize_kaminari! and return
-      elsif defined?(WillPaginate::CollectionMethods)
-        initialize_will_paginate! and return
-      end
-      # If neither is loaded, we can safely attempt these requires.
-      unless ApiPagination.paginator == :will_paginate
-        begin
-          require 'kaminari'
-          initialize_kaminari! and return
-        rescue LoadError
-        end
-      end
-
-      begin
-        require 'will_paginate'
-        initialize_will_paginate! and return
-      rescue LoadError
-      end
-
-      STDERR.puts <<-EOC
-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
-
-    def self.initialize_kaminari!
-      require 'kaminari/models/array_extension'
-      ApiPagination.instance_variable_set(:@paginator, :kaminari)
-    end
-
-    def self.initialize_will_paginate!
-      WillPaginate::CollectionMethods.module_eval do
-        def first_page?() !previous_page end
-        def last_page?() !next_page end
-      end
+begin; require 'rails'; rescue LoadError; end
+if defined?(ActionController::Base)
+  require 'rails/pagination'
+  ActionController::Base.send(:include, Rails::Pagination)
+end
 
-      ApiPagination.instance_variable_set(:@paginator, :will_paginate)
-    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 = 4
-    MINOR = 0
+    MINOR = 1
     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] || route_setting(: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
@@ -29,6 +34,7 @@ module Grape
       base.class_eval do
         def self.paginate(options = {})
           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

@@ -1,15 +1,17 @@
+require 'support/numbers_controller'
+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
 
-require 'support/numbers_controller'
-require 'support/numbers_api'
-require 'api-pagination'
-
-require 'will_paginate/array' if ApiPagination.paginator == :will_paginate
+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: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - David Celis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-13 00:00:00.000000000 Z
+date: 2015-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
@@ -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