lhs 5.3.0 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b5e2d8c23fc37ece5d7b13aebd02f43df60aec96
-  data.tar.gz: 650560241439a1cb5b97c86894ef4a5e133d5bd4
+  metadata.gz: 80529532ef8aaafcbe7822abac42c0082f2b2b32
+  data.tar.gz: f3b872fa678981d24ccfdcc24af642a397cffac4
 SHA512:
-  metadata.gz: 7d086164639d3fd4b3a40a772c2c98360cf212f6b58e6d55a5debe7317daecb341e42aec62948783e79f3eb18f398a607a9cffc99a7828d73f9fc02c894cc36a
-  data.tar.gz: 329fbdb7a8edc677a156588061af8e99e9a15db6bec9684f50e057157f6c4489fd1eb71d5c58c8378bb7e194682b2679e77b58c0ada1f3fc2b012bdfc70c2e9d
+  metadata.gz: bbfea24429cac66bfc5684d31411ed975456d52be8110df299dcd762b2771205e4827b9fcb183305e9444cd0f3e3165fc8b3cf055c5352504f485fbb45cd890a
+  data.tar.gz: 47678b919459a2a896995a01588d1c29876982324872d889dbef21297ff57dc76674561fae8d1f98062ab6dc6e93058c9e9cd608b1cb373c89db4a23b1c3a3c0

data/README.md

@@ -449,7 +449,7 @@ unless user.valid?
 end
 ```
 
-## How to work with paginated APIs
+## Pagination
 
 LHS supports paginated APIs and it also supports various pagination strategies and by providing configuration possibilities.
 
@@ -520,6 +520,40 @@ end
 
 In case of paginated resources it's important to know the difference between [count vs. length](#count-vs-length)
 
+### Pagination Chains
+
+You can use chainable pagination in combination with query chains:
+
+```ruby
+  class Record < LHS::Record
+    endpoint 'http://local.ch/records'
+  end
+  Record.page(3).per(20).where(color: 'blue')
+  # http://local.ch/records?offset=40&limit=20&color=blue
+```
+
+The applied pagination strategy depends on the actual configured pagination, so the interface is the same for all strategies:
+
+```ruby
+  class Record < LHS::Record
+    endpoint 'http://local.ch/records'
+    configuration pagination_strategy: 'page'
+  end
+  Record.page(3).per(20).where(color: 'blue')
+  # http://local.ch/records?page=3&limit=20&color=blue
+```
+
+```ruby
+  class Record < LHS::Record
+    endpoint 'http://local.ch/records'
+    configuration pagination_strategy: 'start'
+  end
+  Record.page(3).per(20).where(color: 'blue')
+  # http://local.ch/records?start=41&limit=20&color=blue
+```
+
+`limit(argument)` is an alias for `per(argument)`. Take notice that `limit` without argument instead, makes the query resolve and provides the current limit from the responds.
+
 ### Partial Kaminari support
 
 LHS implements an interface that makes it partially working with Kaminari.
@@ -531,8 +565,7 @@ The kaminari’s page parameter is in params[:page]. For example, you can use ka
 params[:page] = 0 if params[:page].nil?
 page = params[:page].to_i
 limit = 100
-offset = (page - 1) * limit
-@items = Record.where({ limit: limit, offset: offset }))
+@items = Record.page(page).per(limit)
 ```
 
 ```ruby

data/lib/lhs/concerns/record/all.rb

@@ -5,8 +5,6 @@ class LHS::Record
   module All
     extend ActiveSupport::Concern
 
-    DEFAULT_LIMIT = 100
-
     module ClassMethods
       # Should be an edge case but sometimes all objects from a certain resource
       # are required. In this case we load the first page with the default max limit,
@@ -14,7 +12,7 @@ class LHS::Record
       # for the following pages and concatenate all the results in order to return
       # all the objects for a given resource.
       def all(params = {})
-        limit = params[limit_key] || DEFAULT_LIMIT
+        limit = params[limit_key] || LHS::Pagination::DEFAULT_LIMIT
         data = request(params: params.merge(limit_key => limit))
         request_all_the_rest(data, params) if paginated?(data._raw)
         data._record.new(LHS::Data.new(data, nil, self))

data/lib/lhs/concerns/record/batch.rb

@@ -20,7 +20,7 @@ class LHS::Record
       def find_in_batches(options = {})
         fail 'No block given' unless block_given?
         start = options[:start] || 1
-        batch_size = options[:batch_size] || 100
+        batch_size = options[:batch_size] || LHS::Pagination::DEFAULT_LIMIT
         params = options[:params] || {}
         loop do # as suggested by Matz
           data = request(params: params.merge(limit: batch_size, offset: start))

data/lib/lhs/concerns/record/chainable.rb

@@ -18,6 +18,18 @@ class LHS::Record
       def options(hash = nil)
         Chain.new(self, Option.new(hash))
       end
+
+      def page(page)
+        Chain.new(self, Pagination.new(page: page))
+      end
+
+      def per(limit)
+        Chain.new(self, Pagination.new(per: limit))
+      end
+
+      def limit(argument = nil)
+        Chain.new(self, Pagination.new(per: argument))
+      end
     end
 
     # Link: A part of a chain
@@ -26,6 +38,10 @@ class LHS::Record
         @hash = hash
       end
 
+      def [](parameter)
+        @hash[parameter]
+      end
+
       def to_hash
         @hash
       end
@@ -39,6 +55,10 @@ class LHS::Record
     class Option < Link
     end
 
+    # Pagination: Part of the chain that will be used to controll pagination
+    class Pagination < Link
+    end
+
     # A sequence of links
     class Chain
 
@@ -99,6 +119,19 @@ class LHS::Record
         push Option.new(hash)
       end
 
+      def page(page)
+        push Pagination.new(page: page)
+      end
+
+      def per(per)
+        push Pagination.new(per: per)
+      end
+
+      def limit(argument = nil)
+        return resolve.limit if argument.blank?
+        push Pagination.new(per: argument)
+      end
+
       def find(args)
         @record_class.find(args, chain_options)
       end
@@ -117,6 +150,11 @@ class LHS::Record
         chain_options
       end
 
+      # Returns a hash of pagination values
+      def pagination_values_hash
+        chain_pagination
+      end
+
       protected
 
       def method_missing(name, *args, &block)
@@ -132,7 +170,10 @@ class LHS::Record
 
       def resolve
         @resolved ||= @record_class.new(
-          @record_class.request(chain_options.merge(params: chain_parameters))
+          @record_class.request(
+            chain_options
+              .merge(params: chain_parameters.merge(chain_pagination))
+          )
         )
       end
 
@@ -151,6 +192,25 @@ class LHS::Record
         merge_links @chain.select { |link| link.is_a? Option }
       end
 
+      def chain_pagination
+        resolve_pagination @chain.select { |link| link.is_a? Pagination }
+      end
+
+      def resolve_pagination(links)
+        return {} if links.empty?
+        page = 1
+        per = LHS::Pagination::DEFAULT_LIMIT
+        links.each do |link|
+          page = link[:page] if link[:page].present?
+          per = link[:per] if link[:per].present?
+        end
+        pagination = @record_class.pagination_class
+        {
+          @record_class.pagination_key => pagination.page_to_offset(page, per),
+          @record_class.limit_key => per
+        }
+      end
+
       def merge_links(links)
         hash = {}
         links.each do |link|

data/lib/lhs/concerns/record/pagination.rb

@@ -12,16 +12,20 @@ class LHS::Record
     end
 
     module ClassMethods
-      def pagination(data)
-        case data._record.pagination_strategy.to_sym
+      def pagination_class
+        case pagination_strategy.to_sym
         when :page
-          PagePagination.new(data)
+          LHS::PagePagination
         when :start
-          StartPagination.new(data)
+          LHS::StartPagination
         else
-          OffsetPagination.new(data)
+          LHS::OffsetPagination
         end
       end
+
+      def pagination(data)
+        pagination_class.new(data)
+      end
     end
   end
 end

data/lib/lhs/pagination.rb

@@ -1,5 +1,7 @@
 # Pagination is used to navigate paginateable collections
-class Pagination
+class LHS::Pagination
+
+  DEFAULT_LIMIT = 100
 
   delegate :_record, to: :data
   attr_accessor :data
@@ -18,7 +20,7 @@ class Pagination
   end
 
   def limit
-    data._raw[_record.limit_key.to_sym] || LHS::Record::DEFAULT_LIMIT
+    data._raw[_record.limit_key.to_sym] || LHS::Pagination::DEFAULT_LIMIT
   end
 
   def offset
@@ -62,9 +64,13 @@ class Pagination
   def total_pages
     (total.to_f / limit).ceil
   end
+
+  def self.page_to_offset(page, _limit)
+    page
+  end
 end
 
-class PagePagination < Pagination
+class LHS::PagePagination < LHS::Pagination
 
   def current_page
     offset
@@ -73,10 +79,9 @@ class PagePagination < Pagination
   def next_offset
     current_page + 1
   end
-
 end
 
-class StartPagination < Pagination
+class LHS::StartPagination < LHS::Pagination
 
   def current_page
     (offset + limit - 1) / limit
@@ -86,9 +91,12 @@ class StartPagination < Pagination
     offset + limit
   end
 
+  def self.page_to_offset(page, limit = LHS::Pagination::DEFAULT_LIMIT)
+    (page - 1) * limit + 1
+  end
 end
 
-class OffsetPagination < Pagination
+class LHS::OffsetPagination < LHS::Pagination
 
   def current_page
     (offset + limit) / limit
@@ -98,4 +106,7 @@ class OffsetPagination < Pagination
     offset + limit
   end
 
+  def self.page_to_offset(page, limit = LHS::Pagination::DEFAULT_LIMIT)
+    (page - 1) * limit
+  end
 end

data/lib/lhs/version.rb

@@ -1,3 +1,3 @@
 module LHS
-  VERSION = "5.3.0"
+  VERSION = "5.4.0"
 end

data/spec/pagination/pages_left_spec.rb

@@ -8,7 +8,7 @@ describe LHS::Record do
     LHS::Data.new(data_hash, nil, Record)
   end
 
-  let(:pagination) { OffsetPagination.new(data) }
+  let(:pagination) { LHS::OffsetPagination.new(data) }
 
   before(:each) do
     class Record < LHS::Record

data/spec/record/pagination_chain_spec.rb

@@ -0,0 +1,92 @@
+require 'rails_helper'
+
+describe LHS::Record do
+  context 'pagination chain' do
+    context 'default pagination (offset)' do
+      before(:each) do
+        class Record < LHS::Record
+          endpoint 'http://local.ch/records'
+          endpoint 'http://local.ch/records/:id'
+        end
+      end
+
+      it 'allows to chain pagination methods' do
+        request = stub_request(:get, "http://local.ch/records?color=blue&offset=200&limit=100").to_return(body: [].to_json)
+        Record.where(color: 'blue').page(3).first
+        expect(request).to have_been_made.times(1)
+        request = stub_request(:get, "http://local.ch/records?color=blue&offset=20&limit=10").to_return(body: [].to_json)
+        Record.where(color: 'blue').page(3).per(10).first
+        Record.where(color: 'blue').per(10).page(3).first
+        Record.where(color: 'blue').per(20).page(5).per(10).page(3).first
+        expect(request).to have_been_made.times(3)
+      end
+
+      it 'allows to start chains with pagination methods' do
+        request = stub_request(:get, "http://local.ch/records?color=blue&offset=200&limit=100").to_return(body: [].to_json)
+        Record.page(3).where(color: 'blue').first
+        expect(request).to have_been_made.times(1)
+        request = stub_request(:get, "http://local.ch/records?color=blue&offset=20&limit=10").to_return(body: [].to_json)
+        Record.page(3).per(10).where(color: 'blue').first
+        Record.per(10).page(3).where(color: 'blue').first
+        Record.per(20).page(5).where(color: 'blue').per(10).page(3).first
+        expect(request).to have_been_made.times(3)
+      end
+
+      it 'defaults page to 1' do
+        request = stub_request(:get, "http://local.ch/records?limit=10&offset=0").to_return(body: [].to_json)
+        Record.per(10).first
+        Record.per(10).page("").first
+        expect(request).to have_been_made.times(2)
+      end
+
+      it 'provides limit as alias for per' do
+        request = stub_request(:get, "http://local.ch/records?limit=10&offset=0").to_return(body: [].to_json)
+        Record.limit(10).first
+        Record.page("").limit(10).first
+        expect(request).to have_been_made.times(2)
+      end
+    end
+
+    context 'start pagination' do
+      before(:each) do
+        class Record < LHS::Record
+          configuration pagination_strategy: 'start', pagination_key: 'start'
+          endpoint 'http://local.ch/records'
+          endpoint 'http://local.ch/records/:id'
+        end
+      end
+
+      it 'allows to chain pagination methods' do
+        request = stub_request(:get, "http://local.ch/records?color=blue&start=201&limit=100").to_return(body: [].to_json)
+        Record.where(color: 'blue').page(3).first
+        expect(request).to have_been_made.times(1)
+        request = stub_request(:get, "http://local.ch/records?color=blue&start=21&limit=10").to_return(body: [].to_json)
+        Record.where(color: 'blue').page(3).per(10).first
+        Record.where(color: 'blue').per(10).page(3).first
+        Record.where(color: 'blue').per(20).page(5).per(10).page(3).first
+        expect(request).to have_been_made.times(3)
+      end
+    end
+
+    context 'page pagination' do
+      before(:each) do
+        class Record < LHS::Record
+          configuration pagination_strategy: 'page', pagination_key: 'page'
+          endpoint 'http://local.ch/records'
+          endpoint 'http://local.ch/records/:id'
+        end
+      end
+
+      it 'allows to chain pagination methods' do
+        request = stub_request(:get, "http://local.ch/records?color=blue&page=3&limit=100").to_return(body: [].to_json)
+        Record.where(color: 'blue').page(3).first
+        expect(request).to have_been_made.times(1)
+        request = stub_request(:get, "http://local.ch/records?color=blue&page=3&limit=10").to_return(body: [].to_json)
+        Record.where(color: 'blue').page(3).per(10).first
+        Record.where(color: 'blue').per(10).page(3).first
+        Record.where(color: 'blue').per(20).page(5).per(10).page(3).first
+        expect(request).to have_been_made.times(3)
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lhs
 version: !ruby/object:Gem::Version
-  version: 5.3.0
+  version: 5.4.0
 platform: ruby
 authors:
 - https://github.com/local-ch/lhs/graphs/contributors
@@ -304,6 +304,7 @@ files:
 - spec/record/new_spec.rb
 - spec/record/options_spec.rb
 - spec/record/paginatable_collection_spec.rb
+- spec/record/pagination_chain_spec.rb
 - spec/record/pagination_spec.rb
 - spec/record/persisted_spec.rb
 - spec/record/request_spec.rb
@@ -343,7 +344,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements:
 - Ruby >= 1.9.2
 rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Rails gem providing an easy, active-record-like interface for http json services
@@ -441,6 +442,7 @@ test_files:
 - spec/record/new_spec.rb
 - spec/record/options_spec.rb
 - spec/record/paginatable_collection_spec.rb
+- spec/record/pagination_chain_spec.rb
 - spec/record/pagination_spec.rb
 - spec/record/persisted_spec.rb
 - spec/record/request_spec.rb