jsonapi-query_builder 0.1.6.pre → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edcba945298b8eadf8c9eb952ee3fed13ba3c8c822afa15dea5126102b689584
-  data.tar.gz: acb2b63e334270e21874c4985467c29953faa2abda3af6065aac26b0963767af
+  metadata.gz: 51c9f4a8cc7fb70d6ca5a535cdc3386e97231960b915b02af356126b57d80609
+  data.tar.gz: 9a1684797aa2b39a67c66226da08c0adf326133e4d51190a78f34817e4fc288b
 SHA512:
-  metadata.gz: d80d0e5ac1d07327c1f8737eb5b52439022914238a650ee926175c9f2e3b6f1bf0abecb15812e3e8f8241f8d607a5c2a8b9094169a1ba2e869363a4ecc588a0e
-  data.tar.gz: a17154de4293836988b82af81fef9e2a925f9a153d5ba1ae161178e75ad7b6571a0c5f38b2f0f3b96661f001ec3442191b70cdc85754489ebbd80cee78a4bb21
+  metadata.gz: 70121ffb0d3419bfddff71778b6d4214e4de00c9f61f0bbd272ff6ab5f0a9e848f04c37124cc911371909326fa1f1a41cf1e401f2cd4dcc56e309cc323e2b9fd
+  data.tar.gz: ed296c71cf3bfdc1b46ee995fad2c2de965b38bafad1cad00f8571e55e09a83f18627b36360e231f68e9015b211fcefde2686ba8ef41bdce8c4060dc6fc32506

data/.github/workflows/lint.yml

@@ -0,0 +1,31 @@
+name: lint
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  standardrb:
+    runs-on: ubuntu-18.04
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - name: standardrb
+        run: bundle exec standardrb
+
+  rubocop-rspec:
+    runs-on: ubuntu-18.04
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: rubocop
+        run: bundle exec rubocop --only RSpec

data/.github/workflows/spec.yml

@@ -0,0 +1,23 @@
+name: spec
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+jobs:
+  rake-spec:
+    runs-on: ubuntu-18.04
+    strategy:
+      matrix:
+        ruby: [2.5, 2.6, 2.7, 3.0]
+
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - name: rake spec
+        run: bundle exec rake spec

data/.gitignore

@@ -9,5 +9,4 @@
 
 # rspec failure tracking
 .rspec_status
-Gemfile.lock
 *.gem

data/.rubocop.yml

@@ -4,5 +4,8 @@ require:
 RSpec/NestedGroups:
   Max: 4
 
+RSpec/MultipleMemoizedHelpers:
+  Max: 7
+
 AllCops:
   NewCops: enable

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# 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.
+- [#9](https://github.com/infinum/jsonapi-query_builder/pull/9): added github actions
+
+## 0.1.8 (2021-01-25)
+
+- [#8](https://github.com/infinum/jsonapi-query_builder/pull/8): add support for ruby 3.0
+

data/Gemfile.lock

@@ -0,0 +1,135 @@
+PATH
+  remote: .
+  specs:
+    jsonapi-query_builder (0.2.0)
+      activerecord (>= 5)
+      pagy (~> 3.5)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    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.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)
+    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)
+    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.6)
+    regexp_parser (2.1.1)
+    rexml (3.2.5)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+    rubocop (1.20.0)
+      parallel (~> 1.10)
+      parser (>= 3.0.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml
+      rubocop-ast (>= 1.9.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      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.5.0)
+      rubocop (~> 1.19)
+    ruby-progressbar (1.11.0)
+    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 (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
+
+BUNDLED WITH
+   2.1.4

data/README.md

@@ -1,4 +1,4 @@
-# Jsonapi::QueryBuilder
+# Jsonapi::QueryBuilder ![lint](https://github.com/infinum/jsonapi-query_builder/workflows/lint/badge.svg)![spec](https://github.com/infinum/jsonapi-query_builder/workflows/spec/badge.svg)
 
 `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. 
@@ -27,9 +27,14 @@ 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 :first_name, :last_name, :email
+  sorts_by :last_name
+  sorts_by :first_name, ->(collection, direction) { collection.order(name: direction) }
+  sorts_by :email, EmailSort
 
   ## filtering
   filters_by :first_name
@@ -54,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
@@ -71,14 +99,26 @@ are passed directly to the underlying active record relation, so the usual order
 ```ruby
 default_sort created_at: :desc
 ```
-#### Enabling sorting for attributes
+#### Enabling simple sorting for attributes
 `sorts_by` denotes which attributes can be used for sorting. Sorting parameters are usually parsed from the
-`json:api` sort query parameter in order they are given. So `sort=-first_name,email` would translate to 
-`{ first_name: :desc, email: :asc }`
+`json:api` sort query parameter in the order they are given. So `sort=-first_name,email` would translate to
+`{ first_name: :desc, email: :asc }` 
+```ruby
+sorts_by :first_name
+sorts_by :email
+```
+#### Sorting with lambdas
+`sorts_by` also supports passing a lambda to implement a custom order or reorder function. The parameters passed to the 
+lamdba are collection and the direction of the order, which is either `:desc` or `:asc`.
 ```ruby
-sorts_by :first_name, :email
+sorts_by :first_name, ->(collection, direction) { collection.order(name: direction) }
 ```
 
+#### Sorting with sort classes
+But since we're devout followers of the SOLID principles, we can define a sort class that responds to
+`#results` method, which returns the sorted collection. Under the hood the sort class is initialized with
+the current scope and the direction parameter.
+
 ### Filtering
 
 #### Simple exact match filters
@@ -94,10 +134,11 @@ filters_by :email, ->(collection, query) { collection.where('email ilike ?', "%#
 ```
 
 #### Filter classes
-But since we're devout followers of the SOLID principles, we can define a filter class that responds to
-`#results` method, which returns the filtered collection results. Under the hood the filter class is initialized with
-the current scope and the query parameter is passed to the call method. This is great if you're using query objects for
-ActiveRecord scopes, you can easily use them to filter as well.
+We can define a filter class that responds to `#results` method, which returns the filtered collection results. Under
+the hood the filter class is initialized with the current scope and the query parameter. However, if the object responds
+to a `call` method it sends the current scope and the query parameter to that instead. This is great if you're using
+query objects for ActiveRecord scopes, you can easily use them to filter with as well.
+
 ```ruby
 filters_by :type, TypeFilter
 ```
@@ -150,9 +191,12 @@ filters_by :type, TypeFilter, if: :correct_type?
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can
 also run `bin/console` for an interactive prompt that will allow you to experiment.
 
+We're using `standardrb` and `lefthook`. You can install lefthook hooks via `lefthook install`. It will run linters and
+standardrb checks before commits, and a bundle audit + whole spec suite before push.
+
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the
-version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version,
-push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+version number in `version.rb`, and then run `LEFTHOOK=0 bundle exec rake release`, which will create a git tag for the
+version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/jsonapi-query_builder.gemspec

@@ -36,15 +36,20 @@ Gem::Specification.new do |spec|
   spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.required_ruby_version = "~> 2.5"
+  spec.required_ruby_version = ">= 2.5"
 
-  spec.add_runtime_dependency "activerecord", ">= 5", "<= 6.1"
+  spec.add_runtime_dependency "activerecord", ">= 5"
   spec.add_runtime_dependency "pagy", "~> 3.5"
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "standardrb"
+  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/lefthook.yml

@@ -2,13 +2,13 @@ lint:
   commands: &lint
     lint-frozen-strings:
       glob: "*.rb"
-      run: bundle exec rubocop {staged_files} --only Style/FrozenStringLiteralComment,Layout/EmptyLineAfterMagicComment --format quiet --auto-correct
+      run: bundle exec rubocop --only Style/FrozenStringLiteralComment,Layout/EmptyLineAfterMagicComment --format quiet --auto-correct
 
 rubocop:
   commands: &rubocop
     rubocop-rspec:
       glob: "spec/*"
-      run: bundle exec rubocop {staged_files} --only RSpec --format quiet
+      run: bundle exec rubocop --only RSpec --format quiet
 
 pre-commit:
   parallel: true

data/lib/jsonapi/query_builder/base_filter.rb

@@ -5,11 +5,14 @@ module Jsonapi
     class BaseFilter
       attr_reader :collection, :query
 
+      # @param [ActiveRecord::Relation] collection
+      # @param [String] query the query value used for filtering
       def initialize(collection, query)
         @collection = collection
         @query = query
       end
 
+      # @return [ActiveRecord::Relation] Collection with the filter applied
       def results
         raise NotImplementedError, "#{self.class} should implement #results"
       end

data/lib/jsonapi/query_builder/base_query.rb

@@ -1,41 +1,57 @@
 # frozen_string_literal: true
 
-require "jsonapi/query_builder/mixins/filtering"
+require "jsonapi/query_builder/mixins/filter"
 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
-      include Mixins::Filtering
+      include Mixins::Filter
       include Mixins::Include
       include Mixins::Paginate
       include Mixins::Sort
 
-      attr_reader :collection, :params
+      attr_accessor :collection, :params
 
+      # @param [ActiveRecord::Relation] collection
+      # @param [Hash] params Json:Api query parameters
       def initialize(collection, params)
         @collection = collection
         @params = params.deep_symbolize_keys
       end
 
+      # @return [ActiveRecord::Relation] A collection with eager loaded relationships based on include params, filtered,
+      #   ordered and lastly, paginated.
+      # @note Pagination details are saved to an instance variable and can be accessed via the #pagination_details attribute reader
       def results
         collection
-          .yield_self(&method(:sort))
           .yield_self(&method(:add_includes))
+          .yield_self(&method(:sort))
           .yield_self(&method(:filter))
           .yield_self(&method(:paginate))
       end
 
+      # @param [integer, string] id
+      # @return [Object]
+      # @raise [ActiveRecord::RecordNotFound] if the record by the id is not found
       def find(id)
         find_by! id: id
       end
 
+      # Finds the record by the id parameter the class is instantiated with
+      # @return (see #find)
+      # @raise (see #find)
       def record
         find_by! id: params[:id]
       end
 
+      # @param [Hash] kwargs Attributes with required values
+      # @return (see #find)
+      # @raise [ActiveRecord::RecordNotFound] if the record by the arguments is not found
       def find_by!(**kwargs)
         add_includes(collection).find_by!(kwargs)
       end

data/lib/jsonapi/query_builder/base_sort.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module QueryBuilder
+    class BaseSort
+      attr_reader :collection, :direction
+
+      # @param [ActiveRecord::Relation] collection
+      # @param [Symbol] direction of the ordering, one of :asc or :desc
+      def initialize(collection, direction)
+        @collection = collection
+        @direction = direction
+      end
+
+      # @return [ActiveRecord::Relation] Collection with order applied
+      def results
+        raise NotImplementedError, "#{self.class} should implement #results"
+      end
+    end
+  end
+end

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/filter.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module QueryBuilder
+    module Mixins
+      module Filter
+        extend ActiveSupport::Concern
+
+        class_methods do
+          def supported_filters
+            @supported_filters || {}
+          end
+
+          # Registers an attribute to filter by. Filters are applied in the order they are registered, if they are
+          # applicable, so in-memory filters should be registered last.
+          #
+          # @param [Symbol] attribute The attribute which can be used to filter by
+          # @param [proc, Class] filter A proc or a filter class, defaults to a simple where(attribute => query)
+          # @param [Hash] options Additional filter options
+          # @option options [Symbol] :query_parameter used to override the filter query parameter name
+          # @option options [Boolean] :allow_nil changes the filter conditional to allow explicit checks for an
+          #   attribute null value
+          # @option options [proc, Symbol] :if Define the conditional for applying the filter. If passed a symbol, a
+          #   method with that name is invoked on the instantiated filter object
+          # @option options [proc, Symbol] :unless Define the conditional for applying the filter. If passed a symbol, a
+          #   method with that name is invoked on the instantiated filter object
+          #
+          # @example Change the query parameter name
+          #   filters_by :first_name, query_parameter: 'name'
+          #   # => collection.where(first_name: params.dig(:filter, :name)) if params.dig(:filter, :name).present?
+          #
+          # @example Allow checks for null values
+          #   filters_by :first_name, allow_nil: true
+          #   # => collection.where(first_name: params.dig(:filter, :first_name)) if params[:filter]&.key?(:first_name)
+          #
+          # @example Change the filter condition
+          #   filters_by :first_name, if: ->(query) { query.length >= 2 }
+          #   # => collection.where(first_name: params.dig(:filter, :first_name)) if params.dig(:filter, :first_name) >= 2
+          #   filters_by :first_name, unless: ->(query) { query.length < 2 }
+          #   # => collection.where(first_name: params.dig(:filter, :first_name)) unless params.dig(:filter, :first_name) < 2
+          #   filters_by :type, TypeFilter, if: :correct_type?
+          #   # => TypeFilter.new(collection, query).yield_self { |filter| filter.results if filter.correct_type? }
+          def filters_by(attribute, filter = nil, **options)
+            filter ||= ->(collection, query) { collection.where(attribute => query) }
+            @supported_filters = {**supported_filters, attribute => [filter, options]}
+          end
+        end
+
+        # Filters the passed relation with the default filter params (parsed from the queries params) or with explicitly
+        # passed filter parameters.
+        # Iterates through registered filters so that the filter application order is settable from the backend side
+        # instead of being dependent on the query order from the clients. If the filter condition for the filter
+        # strategy is met, then the filter is applied to the collection. If the strategy responds to a call method it
+        # calls it with the collection and parameter's parsed sort direction, otherwise it instantiates the filter class
+        # with the collection and the parameter's query value and calls for the results.
+        # @param [ActiveRecord::Relation] collection
+        # @param [Object] filter_params Optional explicit filter params
+        # @return [ActiveRecord::Relation, Array] An AR relation is returned unless filters need to resort to in-memory
+        #   filtering strategy, then an array is returned.
+        def filter(collection, filter_params = send(:filter_params))
+          self.class.supported_filters.reduce(collection) do |filtered_collection, supported_filter|
+            filter, options = serialize_filter(supported_filter, collection: filtered_collection, params: filter_params)
+
+            next filtered_collection unless options[:conditions].all? { |type, condition|
+              check_condition(condition, type, filter: filter, query: options[:query])
+            }
+
+            filter.respond_to?(:call) ? filter.call(filtered_collection, options[:query]) : filter.results
+          end
+        end
+
+        private
+
+        def filter_params
+          params[:filter] || {}
+        end
+
+        def serialize_filter(supported_filter, collection:, params:)
+          attribute, (filter, options) = *supported_filter
+
+          options[:query_parameter] = options[:query_parameter]&.to_sym || attribute
+          options[:query] = params[options[:query_parameter]].presence
+          options[:conditions] = options.slice(:if, :unless).presence ||
+            {if: options[:query].present? || options[:allow_nil] && params.key?(options[:query_parameter])}
+
+          filter = filter.new(collection, options[:query]) unless filter.respond_to?(:call)
+
+          [filter, options]
+        end
+
+        def check_condition(condition, type, **opts)
+          (type == :if) == case condition
+          when Proc
+            condition.call(opts[:query])
+          when Symbol
+            opts[:filter].send(condition)
+          else
+            condition
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -4,6 +4,11 @@ module Jsonapi
   module QueryBuilder
     module Mixins
       module Include
+        # Eager loads the relationships that will be included in the response, based on the Json:Api
+        # include query parameter.
+        # @param [ActiveRecord::Relation] collection
+        # @param [Object] include_params Optional explicit include params
+        # @return [ActiveRecord::Relation] Collection with eager loaded included relations
         def add_includes(collection, include_params = send(:include_params))
           collection.includes(formatted_include_params(include_params))
         end

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

@@ -4,14 +4,30 @@ 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
 
+        # Paginates the collection and returns the requested page. Also sets the pagination details that can be used for
+        # displaying metadata in the Json:Api response.
+        # @param [ActiveRecord::Relation] collection
+        # @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/param.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Jsonapi
+  module QueryBuilder
+    module Mixins
+      module Sort
+        class Param
+          attr_reader :descending, :attribute
+
+          def initialize(param)
+            @descending, @attribute = deserialize(param)
+          end
+
+          class << self
+            def deserialize_params(sort_params)
+              (sort_params || "").split(",").map(&method(:new))
+            end
+          end
+
+          def deserialize(param)
+            _, descending, attribute = param.strip.match(/^(?<descending>-)?(?<attribute>.*)$/).to_a
+
+            [descending, attribute]
+          end
+
+          def serialize
+            [descending, attribute].compact.join
+          end
+
+          def direction
+            descending.present? ? :desc : :asc
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
+require "jsonapi/query_builder/mixins/sort/param"
+require "jsonapi/query_builder/errors/unpermitted_sort_parameters"
+
 module Jsonapi
   module QueryBuilder
     module Mixins
       module Sort
         extend ActiveSupport::Concern
 
-        UnpermittedSortParameters = Class.new ArgumentError
-
         class_methods do
           attr_reader :_default_sort
 
@@ -15,28 +16,57 @@ module Jsonapi
             @_unique_sort_attributes || [id: :asc]
           end
 
-          def _sort_attributes
-            @_sort_attributes || []
+          def supported_sorts
+            @supported_sorts || {}
           end
 
+          # Ensures deterministic ordering. Defaults to :id in ascending direction.
+          # @param [Array<Symbol, String, Hash>] attributes An array of attributes or a hash with the attribute and it's
+          #   order direction.
           def unique_sort_attributes(*attributes)
             @_unique_sort_attributes = attributes
           end
+
           alias_method :unique_sort_attribute, :unique_sort_attributes
 
+          # The :default_sort: can be set to sort by any field like `created_at` timestamp or similar. It is only used
+          # if no sort parameter is set, unlike the `unique_sort_attribute` which is always appended as the last sort
+          # attribute. The parameters are passed directly to the underlying active record relation, so the usual
+          # ordering options are possible.
+          # @param [Symbol, Hash] options A default sort attribute or a Hash with the attribute and it's order direction.
           def default_sort(options)
             @_default_sort = options
           end
 
-          def sorts_by(*attributes)
-            @_sort_attributes = _sort_attributes + attributes
+          # Registers attribute that can be used for sorting. Sorting parameters are usually parsed from the `json:api`
+          # sort query parameter in the order they are given.
+          # @param [Symbol] attribute The "sortable" attribute
+          # @param [proc, Class] sort A proc or a sort class, defaults to a simple order(attribute => direction)
+          def sorts_by(attribute, sort = nil)
+            sort ||= ->(collection, direction) { collection.order(attribute => direction) }
+            @supported_sorts = {**supported_sorts, attribute => sort}
           end
         end
 
+        # Sorts the passed relation with the default sort params (parsed from the queries params) or with explicitly
+        # passed sort parameters.
+        # Parses each sort parameter and looks for the sorting strategy for it, if the strategy responds to a call
+        # method it calls it with the collection and parameter's parsed sort direction, otherwise it instantiates the
+        # sort class with the collection and the parameter's parsed sort direction and calls for the results. Finally it
+        # adds the unique sort attributes to enforce deterministic results. If sort params are blank, it adds the
+        # default sort attributes before setting the unique sort attributes.
+        # @param [ActiveRecord::Relation] collection
+        # @param [Object] sort_params Optional explicit sort params
+        # @return [ActiveRecord::Relation] Sorted relation
+        # @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)
+          ensure_permitted_sort_params!(sort_params) if sort_params
+
           collection
-            .reorder(sort_params.nil? ? self.class._default_sort : formatted_sort_params(sort_params))
-            .tap(&method(:add_unique_order_attributes))
+            .yield_self { |c| add_order_attributes(c, sort_params) }
+            .yield_self(&method(:add_unique_order_attributes))
         end
 
         private
@@ -45,27 +75,30 @@ module Jsonapi
           params[:sort]
         end
 
-        def add_unique_order_attributes(collection)
-          collection.order(*self.class._unique_sort_attributes)
-        end
+        def ensure_permitted_sort_params!(sort_params)
+          unpermitted_parameters = sort_params.map(&:attribute).map(&:to_sym) - self.class.supported_sorts.keys
+          return if unpermitted_parameters.size.zero?
 
-        def formatted_sort_params(sort_params)
-          sort_params
-            .split(",")
-            .map(&:strip)
-            .to_h { |attribute| attribute.start_with?("-") ? [attribute[1..-1], :desc] : [attribute, :asc] }
-            .symbolize_keys
-            .tap(&method(:ensure_permitted_sort_params!))
+          raise Errors::UnpermittedSortParameters, unpermitted_parameters
         end
 
-        def ensure_permitted_sort_params!(sort_params)
-          return if (unpermitted_parameters = sort_params.keys - self.class._sort_attributes.map(&:to_sym)).size.zero?
+        def add_order_attributes(collection, sort_params)
+          return collection if self.class._default_sort.nil? && sort_params.blank?
+          return collection.order(self.class._default_sort) if sort_params.blank?
+
+          sort_params.reduce(collection) do |sorted_collection, sort_param|
+            sort = self.class.supported_sorts.fetch(sort_param.attribute.to_sym)
 
-          raise UnpermittedSortParameters, [
-            unpermitted_parameters.to_sentence,
-            unpermitted_parameters.count == 1 ? "is not a" : "are not",
-            "permitted sort attribute".pluralize(unpermitted_parameters.count)
-          ].join(" ")
+            if sort.respond_to?(:call)
+              sort.call(sorted_collection, sort_param.direction)
+            else
+              sort.new(sorted_collection, sort_param.direction).results
+            end
+          end
+        end
+
+        def add_unique_order_attributes(collection)
+          collection.order(*self.class._unique_sort_attributes)
         end
       end
     end

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.6.pre"
+    VERSION = "0.2.0"
   end
 end

data/lib/jsonapi/query_builder.rb

@@ -4,9 +4,8 @@ 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"
 require "jsonapi/query_builder/base_filter"
+require "jsonapi/query_builder/base_sort"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-query_builder
 version: !ruby/object:Gem::Version
-  version: 0.1.6.pre
+  version: 0.2.0
 platform: ruby
 authors:
 - Jure Cindro
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-01 00:00:00.000000000 Z
+date: 2021-09-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -17,9 +17,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5'
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: '6.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -27,9 +24,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '5'
-    - - "<="
-      - !ruby/object:Gem::Version
-        version: '6.1'
 - !ruby/object:Gem::Dependency
   name: pagy
   requirement: !ruby/object:Gem::Requirement
@@ -100,6 +94,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  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: rubocop-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -128,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.
 
@@ -138,12 +202,15 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".github/workflows/lint.yml"
+- ".github/workflows/spec.yml"
 - ".gitignore"
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile
@@ -154,10 +221,18 @@ files:
 - lib/jsonapi/query_builder.rb
 - lib/jsonapi/query_builder/base_filter.rb
 - lib/jsonapi/query_builder/base_query.rb
-- lib/jsonapi/query_builder/mixins/filtering.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:
@@ -172,14 +247,14 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubygems_version: 3.0.3
 signing_key:

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

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-module Jsonapi
-  module QueryBuilder
-    module Mixins
-      module Filtering
-        extend ActiveSupport::Concern
-
-        class_methods do
-          def supported_filters
-            @supported_filters || {}
-          end
-
-          def filters_by(attribute, filter = nil, **options)
-            filter ||= ->(collection, query) { collection.where(attribute => query) }
-            @supported_filters = {**supported_filters, attribute => [filter, options]}
-          end
-        end
-
-        def filter(collection, filter_params = send(:filter_params))
-          self.class.supported_filters.reduce(collection) do |filtered_collection, supported_filter|
-            filter, options = serialize_filter(supported_filter, collection: filtered_collection, params: filter_params)
-
-            next filtered_collection unless options[:conditions].all? { |type, condition|
-              check_condition(condition, type, filter: filter, query: options[:query])
-            }
-
-            filter.respond_to?(:call) ? filter.call(filtered_collection, options[:query]) : filter.results
-          end
-        end
-
-        private
-
-        def filter_params
-          params[:filter] || {}
-        end
-
-        def serialize_filter(supported_filter, collection:, params:)
-          attribute, (filter, options) = *supported_filter
-
-          options[:query_parameter] = options[:query_parameter]&.to_sym || attribute
-          options[:query] = params[options[:query_parameter]].presence
-          options[:conditions] = options.slice(:if, :unless).presence ||
-            {if: options[:query].present? || options[:allow_nil] && params.key?(options[:query_parameter])}
-
-          filter = filter.new(collection, options[:query]) unless filter.respond_to?(:call)
-
-          [filter, options]
-        end
-
-        def check_condition(condition, type, **opts)
-          (type == :if) == case condition
-          when Proc
-            condition.call(opts[:query])
-          when Symbol
-            opts[:filter].send(condition)
-          else
-            condition
-          end
-        end
-      end
-    end
-  end
-end