jsonapi-query_builder 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f47ebd86badc968ef8a79333f49ac496c067ad6a26c6563cca0257c1e8cdeba2
-  data.tar.gz: ff874753c9a7ba077bf7876a8a598dd01058a0e2f7a2a982dde2fc579342a5d0
+  metadata.gz: c0bbac3427e5cd55ee1f3528925a7d5f06817bef89e232a668821450a8cbedf0
+  data.tar.gz: 622b993193db4a2644187a99099ed5470380dae1d4f576efccf0465d84a8e7f3
 SHA512:
-  metadata.gz: fc7168dad1ea652617381662a8e75cadbb132addb9b78d6af052b15b590d3f031fa143a6508e6f2feb52f82ee9f333892551378fa5a969ac5232bb48ca8b0c8e
-  data.tar.gz: 6ead187ee07d7d9db557c2010b3d2c992c01d05c888ad6a777716380fa565fc9aff54fb39db54120131bbb544418f789f53cade618c55db86d2aec3d03c08a61
+  metadata.gz: 5719e6ab6411803bd98cc6aa06ce8471a19c90f713c4b1c014106338bde1b7d7495bcac4be216349524c92489d5873327ba31cc7d4e99c075249ce6db149a54f
+  data.tar.gz: 6151a1cd285f11ed2f48c7c140442a3f67ba85f656d601d8a5ad4c2c686c973aad0526340a37271194e9400642db951d071d43993f7d37095fc47861ae89daf0

data/CHANGELOG.md

@@ -1,20 +1,36 @@
 # Change log
 
+## 0.3.0 (2021-12-07)
+
+### Enhancements
+
+- Add support for proc and object default
+  sorts [a167f90](https://github.com/infinum/jsonapi-query_builder/commit/a167f90ca718fe62c0899520cd4c5c859f89035b)
+
 ## 0.2.1 (2021-10-04)
 
+### Bugfixes
+
 - [#22](https://github.com/infinum/jsonapi-query_builder/pull/22): Bump allowed pagy version.
 
 ## 0.2.0 (2021-09-29)
+
+### Enhancements
+
 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)
 
+### Enhancements
+
 - [#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)
 
+### Enhancements
+
 - [#8](https://github.com/infinum/jsonapi-query_builder/pull/8): add support for ruby 3.0
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jsonapi-query_builder (0.2.1)
+    jsonapi-query_builder (0.3.0)
       activerecord (>= 5)
       pagy (>= 3.5)
 

data/README.md

@@ -1,7 +1,7 @@
 # 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. 
+collection, usually used in controller index actions.
 
 With the query builder we can easily define logic for query filters, attributes by which we can sort, and delegate
 pagination parameters to the underlying paginator. Included relationships are automatically included via the
@@ -29,7 +29,7 @@ Or install it yourself as:
 class UserQuery < Jsonapi::QueryBuilder::BaseQuery
   ## pagination 
   paginator Jsonapi::QueryBuilder::Paginator::Pagy # default paginator
-  
+
   ## sorting
   default_sort created_at: :desc
   sorts_by :last_name
@@ -54,21 +54,23 @@ end
 ```
 
 The query class is initialized using a collection and query parameters. Since query parameters are referenced explicitly
-we can pass them as an unsafe hash. `Jsonapi::QueryBuilder::BaseQuery` should not be responsible for scoping records based on
-current user permissions, or for any other type of scoping. It's only responsibility is to support the `json:api`
-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.
+we can pass them as an unsafe hash. `Jsonapi::QueryBuilder::BaseQuery` should not be responsible for scoping records
+based on current user permissions, or for any other type of scoping. It's only responsibility is to support
+the `json:api` 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.
+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"
 
@@ -76,6 +78,7 @@ paginator Jsonapi::QueryBuilder::Paginator::Kaminari
 ```
 
 #### Using the Keyset Paginator
+
 ```ruby
 require "jsonapi/query_builder/paginator/keyset"
 
@@ -83,57 +86,80 @@ 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
 collection responses. You can override the `unique_sort_attribute` in the query object.
+
 ```ruby
 # set the unique sort attribute
 unique_sort_attribute :email
 # use compound unique sort attributes
 unique_sort_attributes :created_at, :email
 ````
+
 #### Default sort options
+
 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.
+are passed directly to the underlying active record relation, so the usual ordering options are possible. It is also
+possible to define the default sort with a lambda or by passing a sort object.
+
 ```ruby
+default_sort :created_at
+# or
 default_sort created_at: :desc
+# or
+default_sort ->(collection) { collection.order(created_at: :desc) }
+# or
+default_sort SortObject
 ```
+
 #### 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 the order they are given. So `sort=-first_name,email` would translate to
-`{ first_name: :desc, email: :asc }` 
+`{ 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 
+
+`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, ->(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.
+
+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
+
 ```ruby
 filters_by :first_name
 # => collection.where(first_name: params.dig(:filter, :first_name)) if params.dig(:filter, :first_name).present?
 ```
 
 #### Lambda as a filter
+
 ```ruby
 filters_by :email, ->(collection, query) { collection.where('email ilike ?', "%#{query}%") }
 # => collection.where('email ilike ?', "%#{params.dig(:filter, :email)}%") if params.dig(:filter, :email).present?
 ```
 
 #### Filter classes
+
 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
@@ -142,17 +168,23 @@ query objects for ActiveRecord scopes, you can easily use them to filter with as
 ```ruby
 filters_by :type, TypeFilter
 ```
+
 The filter class could look something like
+
 ```ruby
+
 class TypeFilter < Jsonapi::QueryBuilder::BaseFilter
   def results
     collection.where(type: query.split(','))
   end
 end
 ```
+
 Sometimes you need to perform in-memory filtering, for example when database attributes are encrypted. In that case,
 those filters should be applied last, the order of definition in the query object matters.
+
 ```ruby
+
 class MrnFilter < Jsonapi::QueryBuilder::BaseFilter
   def results
     collection.select { |record| /#{query}/.match?(record.mrn) }
@@ -161,26 +193,34 @@ end
 ```
 
 #### Additional Options
+
 You can override the filter query parameter name by passing the `query_parameter` option.
+
 ```ruby
 filters_by :first_name, query_parameter: 'name'
 # => collection.where(first_name: params.dig(:filter, :name)) if params.dig(:filter, :name).present?
 ```
+
 `allow_nil` option changes the filter conditional to allow explicit checks for an attribute null value.
+
 ```ruby
 filters_by :first_name, allow_nil: true
 # => collection.where(first_name: params.dig(:filter, :first_name)) if params[:filter]&.key?(:first_name)
 ```
+
 The conditional when the filter is applied can also be defined explicitly. Note that these options override the
 `allow_nil` option, as the condition if defined explicitly and you should handle `nil` explicitly as well.
+
 ```ruby
 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
 ```
+
 When you're using a filter class you can pass a symbol to the `:if` and `:unless` options which invokes the method on
 the filter class.
+
 ```ruby
 filters_by :type, TypeFilter, if: :correct_type?
 # => type_filter = TypeFilter.new(collection, query); type_filter.results if type_filter.correct_type?
@@ -202,7 +242,6 @@ version, push git commits and tags, and push the `.gem` file to [rubygems.org](h
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/infinum/jsonapi-query_builder.
 
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/jsonapi/query_builder/base_sort.rb

@@ -7,7 +7,7 @@ module Jsonapi
 
       # @param [ActiveRecord::Relation] collection
       # @param [Symbol] direction of the ordering, one of :asc or :desc
-      def initialize(collection, direction)
+      def initialize(collection, direction = :asc)
         @collection = collection
         @direction = direction
       end

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

@@ -84,7 +84,7 @@ module Jsonapi
 
         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?
+          return sort_by_default(collection) if sort_params.blank?
 
           sort_params.reduce(collection) do |sorted_collection, sort_param|
             sort = self.class.supported_sorts.fetch(sort_param.attribute.to_sym)
@@ -97,6 +97,18 @@ module Jsonapi
           end
         end
 
+        def sort_by_default(collection)
+          default_sort = self.class._default_sort
+
+          if default_sort.is_a?(Symbol) || default_sort.is_a?(Hash)
+            collection.order(default_sort)
+          elsif default_sort.respond_to?(:call)
+            default_sort.call(collection)
+          else
+            default_sort.new(collection).results
+          end
+        end
+
         def add_unique_order_attributes(collection)
           collection.order(*self.class._unique_sort_attributes)
         end

data/lib/jsonapi/query_builder/version.rb

@@ -2,6 +2,6 @@
 
 module Jsonapi
   module QueryBuilder
-    VERSION = "0.2.1"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jsonapi-query_builder
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Jure Cindro
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-10-04 00:00:00.000000000 Z
+date: 2021-12-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord