jsonapi-query_builder 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c919f735d39662624a6cbda5429e5b31941578628bfa6adadf26334a0b9a1f3
-  data.tar.gz: 3ff9cadb9e8b8cea55447e6b86c6c8f3e16953beda7edee3ff8aac7e230753b8
+  metadata.gz: 51c9f4a8cc7fb70d6ca5a535cdc3386e97231960b915b02af356126b57d80609
+  data.tar.gz: 9a1684797aa2b39a67c66226da08c0adf326133e4d51190a78f34817e4fc288b
 SHA512:
-  metadata.gz: 51d7f79e29b103e6aeac59dee1283b09ae3a9b3dc035099e341a2f9891a41fad1d7e05357198b4b08846226ac0421d195b3d583d9936a326003cfab076645ded
-  data.tar.gz: 6f11c9b84669ace622fb6b8d5d8917abeb9ced15ad1dc68e988380e282a7be9aa9d3e73baa317a49212c161c9aa351461c251fd89fd882b5e9c05847626ad698
+  metadata.gz: 70121ffb0d3419bfddff71778b6d4214e4de00c9f61f0bbd272ff6ab5f0a9e848f04c37124cc911371909326fa1f1a41cf1e401f2cd4dcc56e309cc323e2b9fd
+  data.tar.gz: ed296c71cf3bfdc1b46ee995fad2c2de965b38bafad1cad00f8571e55e09a83f18627b36360e231f68e9015b211fcefde2686ba8ef41bdce8c4060dc6fc32506

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Change log
 
+## 0.2.0 (2021-09-29)
+Added support for Kaminari and Keyset pagination strategies in addition to Pagy.
+
+- [#21](https://github.com/infinum/jsonapi-query_builder/pull/21): Extract paginators.
+
 ## 0.1.9 (2021-05-07)
 
 - [#18](https://github.com/infinum/jsonapi-query_builder/pull/18): Remove Ruby `to` version.

data/Gemfile.lock

@@ -1,38 +1,77 @@
 PATH
   remote: .
   specs:
-    jsonapi-query_builder (0.1.9)
+    jsonapi-query_builder (0.2.0)
       activerecord (>= 5)
       pagy (~> 3.5)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (6.1.3.1)
-      activesupport (= 6.1.3.1)
-    activerecord (6.1.3.1)
-      activemodel (= 6.1.3.1)
-      activesupport (= 6.1.3.1)
-    activesupport (6.1.3.1)
+    actionview (6.1.4.1)
+      activesupport (= 6.1.4.1)
+      builder (~> 3.1)
+      erubi (~> 1.4)
+      rails-dom-testing (~> 2.0)
+      rails-html-sanitizer (~> 1.1, >= 1.2.0)
+    activemodel (6.1.4.1)
+      activesupport (= 6.1.4.1)
+    activerecord (6.1.4.1)
+      activemodel (= 6.1.4.1)
+      activesupport (= 6.1.4.1)
+    activesupport (6.1.4.1)
       concurrent-ruby (~> 1.0, >= 1.0.2)
       i18n (>= 1.6, < 2)
       minitest (>= 5.1)
       tzinfo (~> 2.0)
       zeitwerk (~> 2.3)
-    ast (2.4.1)
-    concurrent-ruby (1.1.8)
+    ast (2.4.2)
+    builder (3.2.4)
+    coderay (1.1.3)
+    concurrent-ruby (1.1.9)
+    crass (1.0.6)
     diff-lcs (1.4.4)
+    erubi (1.10.0)
     i18n (1.8.10)
       concurrent-ruby (~> 1.0)
-    lefthook (0.7.2)
+    kaminari (1.2.1)
+      activesupport (>= 4.1.0)
+      kaminari-actionview (= 1.2.1)
+      kaminari-activerecord (= 1.2.1)
+      kaminari-core (= 1.2.1)
+    kaminari-actionview (1.2.1)
+      actionview
+      kaminari-core (= 1.2.1)
+    kaminari-activerecord (1.2.1)
+      activerecord
+      kaminari-core (= 1.2.1)
+    kaminari-core (1.2.1)
+    lefthook (0.7.6)
+    loofah (2.12.0)
+      crass (~> 1.0.2)
+      nokogiri (>= 1.5.9)
+    method_source (1.0.0)
+    mini_portile2 (2.6.1)
     minitest (5.14.4)
-    pagy (3.11.0)
-    parallel (1.20.1)
-    parser (3.0.0.0)
+    nokogiri (1.12.5)
+      mini_portile2 (~> 2.6.1)
+      racc (~> 1.4)
+    pagy (3.14.0)
+    parallel (1.21.0)
+    parser (3.0.2.0)
       ast (~> 2.4.1)
+    pry (0.14.1)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    racc (1.5.2)
+    rails-dom-testing (2.0.3)
+      activesupport (>= 4.2.0)
+      nokogiri (>= 1.6)
+    rails-html-sanitizer (1.4.2)
+      loofah (~> 2.3)
     rainbow (3.0.0)
-    rake (13.0.3)
-    regexp_parser (2.0.3)
+    rake (13.0.6)
+    regexp_parser (2.1.1)
     rexml (3.2.5)
     rspec (3.10.0)
       rspec-core (~> 3.10.0)
@@ -43,48 +82,52 @@ GEM
     rspec-expectations (3.10.1)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-mocks (3.10.1)
+    rspec-mocks (3.10.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.10.0)
-    rspec-support (3.10.1)
-    rubocop (1.7.0)
+    rspec-support (3.10.2)
+    rubocop (1.20.0)
       parallel (~> 1.10)
-      parser (>= 2.7.1.5)
+      parser (>= 3.0.0.0)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml
-      rubocop-ast (>= 1.2.0, < 2.0)
+      rubocop-ast (>= 1.9.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 2.0)
-    rubocop-ast (1.4.0)
-      parser (>= 2.7.1.5)
-    rubocop-performance (1.9.2)
-      rubocop (>= 0.90.0, < 2.0)
+      unicode-display_width (>= 1.4.0, < 3.0)
+    rubocop-ast (1.12.0)
+      parser (>= 3.0.1.1)
+    rubocop-performance (1.11.5)
+      rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
-    rubocop-rspec (2.1.0)
-      rubocop (~> 1.0)
-      rubocop-ast (>= 1.1.0)
+    rubocop-rspec (2.5.0)
+      rubocop (~> 1.19)
     ruby-progressbar (1.11.0)
-    standard (0.11.0)
-      rubocop (= 1.7.0)
-      rubocop-performance (= 1.9.2)
+    sqlite3 (1.4.2)
+    standard (1.3.0)
+      rubocop (= 1.20.0)
+      rubocop-performance (= 1.11.5)
     standardrb (1.0.0)
       standard
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (1.7.0)
+    unicode-display_width (2.1.0)
     zeitwerk (2.4.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
+  activerecord
   bundler (~> 2.0)
   jsonapi-query_builder!
+  kaminari (~> 1.2)
   lefthook
+  pry
   rake (~> 13.0)
   rspec (~> 3.0)
   rubocop-rspec
+  sqlite3
   standard
   standardrb
 

data/README.md

@@ -27,6 +27,9 @@ Or install it yourself as:
 
 ```ruby
 class UserQuery < Jsonapi::QueryBuilder::BaseQuery
+  ## pagination 
+  paginator Jsonapi::QueryBuilder::Paginator::Pagy # default paginator
+  
   ## sorting
   default_sort created_at: :desc
   sorts_by :last_name
@@ -56,6 +59,29 @@ current user permissions, or for any other type of scoping. It's only responsibi
 querying. Use `pundit` or similar for policy scoping, custom query objects for other scoping, and then pass the scoped
 collection to the `Jsonapi::QueryBuilder::BaseQuery` object.
 
+### Pagination
+Pagination support is configurable using the `paginator` method to define the paginator. It defaults to the `Pagy`
+paginator, a lightweight and fast paginator. Other paginators currently supported are `Kaminari` and an implementation
+of keyset pagination. Before using these paginators we need to explicitly require the gems in our Gemfile and the
+paginator file in question. 
+Additionally one can implement it's own paginator by inheriting from `Jsonapi::QueryBuilder::Paginator::BasePaginator`.
+The minimum required implementation is a `#paginate` method that receives page params and returns a page of the
+collection. It can return the pagination details as the second item of the returned array, that can be used in the
+serializer for pagination metadata.
+#### Using the Kaminari Paginator
+```ruby
+require "jsonapi/query_builder/paginator/kaminari"
+
+paginator Jsonapi::QueryBuilder::Paginator::Kaminari
+```
+
+#### Using the Keyset Paginator
+```ruby
+require "jsonapi/query_builder/paginator/keyset"
+
+paginator Jsonapi::QueryBuilder::Paginator::Keyset
+```
+
 ### Sorting
 #### Ensuring deterministic results
 Sorting has a fallback to an unique attribute which defaults to the `id` attribute. This ensures deterministic paginated

data/jsonapi-query_builder.gemspec

@@ -48,4 +48,8 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "standard"
   spec.add_development_dependency "rubocop-rspec"
   spec.add_development_dependency "lefthook"
+  spec.add_development_dependency "kaminari", "~> 1.2"
+  spec.add_development_dependency "activerecord"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "pry"
 end

data/lib/jsonapi/query_builder/base_query.rb

@@ -5,6 +5,8 @@ require "jsonapi/query_builder/mixins/include"
 require "jsonapi/query_builder/mixins/paginate"
 require "jsonapi/query_builder/mixins/sort"
 
+require "jsonapi/query_builder/paginator"
+
 module Jsonapi
   module QueryBuilder
     class BaseQuery

data/lib/jsonapi/query_builder/errors/unpermitted_sort_parameters.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module QueryBuilder
+    module Errors
+      class UnpermittedSortParameters < ArgumentError
+        def initialize(unpermitted_parameters)
+          super [
+            unpermitted_parameters.to_sentence,
+            unpermitted_parameters.count == 1 ? "is not a" : "are not",
+            "permitted sort attribute".pluralize(unpermitted_parameters.count)
+          ].join(" ")
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/query_builder/mixins/paginate.rb

@@ -4,7 +4,20 @@ module Jsonapi
   module QueryBuilder
     module Mixins
       module Paginate
-        include Pagy::Backend
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Sets the paginator used to page the results. Defaults to Pagy
+          #
+          # @param [Jsonapi::QueryBuilder::Paginator::BasePaginator] paginator A subclass of BasePaginator
+          def paginator(paginator)
+            @paginator = paginator
+          end
+
+          def _paginator
+            @paginator || Paginator::Pagy
+          end
+        end
 
         attr_reader :pagination_details
 
@@ -14,9 +27,7 @@ module Jsonapi
         # @param [Object] page_params Optional explicit pagination params
         # @return [ActiveRecord::Relation] Paged collection
         def paginate(collection, page_params = send(:page_params))
-          @pagination_details, records = pagy collection, page: page_params[:number],
-                                                          items: page_params[:size],
-                                                          outset: page_params[:offset]
+          records, @pagination_details = self.class._paginator.new(collection).paginate(page_params)
 
           records
         end

data/lib/jsonapi/query_builder/mixins/sort.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "jsonapi/query_builder/mixins/sort/param"
+require "jsonapi/query_builder/errors/unpermitted_sort_parameters"
 
 module Jsonapi
   module QueryBuilder
@@ -8,8 +9,6 @@ module Jsonapi
       module Sort
         extend ActiveSupport::Concern
 
-        UnpermittedSortParameters = Class.new ArgumentError
-
         class_methods do
           attr_reader :_default_sort
 
@@ -59,7 +58,7 @@ module Jsonapi
         # @param [ActiveRecord::Relation] collection
         # @param [Object] sort_params Optional explicit sort params
         # @return [ActiveRecord::Relation] Sorted relation
-        # @raise [Jsonapi::QueryBuilder::Mixins::Sort::UnpermittedSortParameters] if not all sort parameters are
+        # @raise [Jsonapi::QueryBuilder::Errors::UnpermittedSortParameters] if not all sort parameters are
         #   permitted
         def sort(collection, sort_params = send(:sort_params))
           sort_params = Param.deserialize_params(sort_params)
@@ -80,11 +79,7 @@ module Jsonapi
           unpermitted_parameters = sort_params.map(&:attribute).map(&:to_sym) - self.class.supported_sorts.keys
           return if unpermitted_parameters.size.zero?
 
-          raise UnpermittedSortParameters, [
-            unpermitted_parameters.to_sentence,
-            unpermitted_parameters.count == 1 ? "is not a" : "are not",
-            "permitted sort attribute".pluralize(unpermitted_parameters.count)
-          ].join(" ")
+          raise Errors::UnpermittedSortParameters, unpermitted_parameters
         end
 
         def add_order_attributes(collection, sort_params)

data/lib/jsonapi/query_builder/paginator/base_paginator.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module QueryBuilder
+    module Paginator
+      class BasePaginator
+        attr_reader :collection
+
+        # @param [ActiveRecord::Relation] collection
+        def initialize(collection)
+          @collection = collection
+        end
+
+        # @param [Hash] page_params
+        # @return [[ActiveRecord::Relation, Hash]] Records and pagination details
+        def paginate(page_params)
+          raise NotImplementedError, "#{self.class} should implement ##{__method__}"
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/query_builder/paginator/kaminari.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "kaminari"
+
+module Jsonapi
+  module QueryBuilder
+    module Paginator
+      class Kaminari < BasePaginator
+        def paginate(page_params)
+          paged_collection = collection
+            .page(page_params[:number])
+            .per(page_params[:size])
+            .padding(page_params[:offset])
+
+          [paged_collection, pagination_details(paged_collection, page_params)]
+        end
+
+        private
+
+        def pagination_details(collection, page_params)
+          {
+            number: collection.current_page,
+            size: collection.limit_value,
+            offset: page_params[:offset],
+            total: collection.total_count,
+            total_pages: collection.total_pages,
+            next_page: collection.next_page,
+            prev_page: collection.prev_page
+          }
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/query_builder/paginator/keyset.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "active_record"
+
+module Jsonapi
+  module QueryBuilder
+    module Paginator
+      class Keyset < BasePaginator
+        DEFAULT_DIRECTION = :after
+        DEFAULT_LIMIT = 25
+
+        def paginate(page_params)
+          page_params = extract_pagination_params(page_params)
+          records = apply_pagination(collection, page_params)
+
+          [records, page_params]
+        end
+
+        private
+
+        def extract_pagination_params(params)
+          {
+            column: params.fetch(:column, nil),
+            position: params.fetch(:position, nil),
+            direction: params.fetch(:direction, DEFAULT_DIRECTION),
+            limit: params.fetch(:limit, DEFAULT_LIMIT)
+          }
+        end
+
+        def apply_pagination(collection, pagination_params)
+          column = pagination_params[:column]
+          position = pagination_params[:position]
+          direction = pagination_params[:direction]
+          limit = pagination_params[:limit]
+
+          return collection unless column
+
+          collection = apply_order(collection, column, direction)
+          collection = collection.limit(limit.to_i)
+
+          return collection unless position
+
+          apply_filter(collection, column, position, direction)
+        end
+
+        def apply_order(collection, column, direction)
+          if direction.to_sym == DEFAULT_DIRECTION
+            collection.reorder(collection.arel_table[column].asc)
+          else
+            collection.reorder(collection.arel_table[column].desc)
+          end
+        end
+
+        def apply_filter(collection, column, position, direction)
+          if direction.to_sym == DEFAULT_DIRECTION
+            collection.where(collection.arel_table[column].gt(position))
+          else
+            collection.where(collection.arel_table[column].lt(position))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/jsonapi/query_builder/paginator/pagy.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "pagy"
+require "pagy/extras/items"
+
+module Jsonapi
+  module QueryBuilder
+    module Paginator
+      class Pagy < BasePaginator
+        include ::Pagy::Backend
+
+        def paginate(page_params)
+          @params = {page: page_params}
+
+          pagination_details, records = pagy collection, page: page_params[:number],
+                                                         items: page_params[:size],
+                                                         outset: page_params[:offset]
+          [records, pagination_details]
+        end
+
+        private
+
+        attr_reader :params
+      end
+    end
+  end
+end

data/lib/jsonapi/query_builder/paginator.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require "jsonapi/query_builder/paginator/base_paginator"
+require "jsonapi/query_builder/paginator/pagy"

data/lib/jsonapi/query_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Jsonapi
   module QueryBuilder
-    VERSION = "0.1.9"
+    VERSION = "0.2.0"
   end
 end

data/lib/jsonapi/query_builder.rb

@@ -4,8 +4,6 @@ require "active_support/concern"
 require "active_support/core_ext/array/conversions"
 require "active_support/core_ext/hash/keys"
 require "active_support/core_ext/string/inflections"
-require "pagy"
-require "pagy/extras/items"
 
 require "jsonapi/query_builder/version"
 require "jsonapi/query_builder/base_query"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-query_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Jure Cindro
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-05-07 00:00:00.000000000 Z
+date: 2021-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -136,6 +136,62 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: kaminari
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   `Jsonapi::QueryBuilder` serves the purpose of adding the json api query related SQL conditions to the already scoped collection, usually used in controller index actions.
 
@@ -166,11 +222,17 @@ files:
 - lib/jsonapi/query_builder/base_filter.rb
 - lib/jsonapi/query_builder/base_query.rb
 - lib/jsonapi/query_builder/base_sort.rb
+- lib/jsonapi/query_builder/errors/unpermitted_sort_parameters.rb
 - lib/jsonapi/query_builder/mixins/filter.rb
 - lib/jsonapi/query_builder/mixins/include.rb
 - lib/jsonapi/query_builder/mixins/paginate.rb
 - lib/jsonapi/query_builder/mixins/sort.rb
 - lib/jsonapi/query_builder/mixins/sort/param.rb
+- lib/jsonapi/query_builder/paginator.rb
+- lib/jsonapi/query_builder/paginator/base_paginator.rb
+- lib/jsonapi/query_builder/paginator/kaminari.rb
+- lib/jsonapi/query_builder/paginator/keyset.rb
+- lib/jsonapi/query_builder/paginator/pagy.rb
 - lib/jsonapi/query_builder/version.rb
 homepage: https://github.com/infinum/jsonapi-query_builder
 licenses: