next_page 0.1.1 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ce595b7487e3bad03f114a44e12e9f87ec7dff8044fa652ecc7a9407d395298
-  data.tar.gz: 8e2eb4b8b7249254b18f05f1e6bbff3d37f94ce245447ed528036ca3df61ef20
+  metadata.gz: 48258d40caac39b331bba8d81ea99fcbb5523bab818616243149a952c4c286ea
+  data.tar.gz: b52465382e154b636c18f1b0c881cc3c5a4908aa4410a959fe4696904764846b
 SHA512:
-  metadata.gz: e0ed8f02d7aaf6122c89dfd4bda2cba1f7f3603f62e6b26a9f72497d597d075828f02c70855918854cd56cd6945477bd6c8e6f6625157be72477690bb1929881
-  data.tar.gz: 5b38a774a9ae623bab874b486fc48c3dcd3aa62f27c50ce6302dcea24a27254561e81afafd0dc79e05e7c5623769928f1ba94875ecd2bbe6b4b02da9ce1add9f
+  metadata.gz: ecdb889ce15846cda3025f6d8c07f61e2901c7633e191c88b8c9aedea79105fd639d95e9abbed8f1cfed8be98ab885f7be4cd67cf5d87d451812e93cceb929b6
+  data.tar.gz: 3a1aea4f5ca07e1656e61bc89a4cae38cfb0fe9523d26a7fb5a3064661e87c06c1c1f811fd3191b5f262b5186eabf38e3a40414064d4c1d3eb5bd56d10bb7704

data/README.md

@@ -1,3 +1,6 @@
+[![Gem Version](https://badge.fury.io/rb/next_page.svg)](https://badge.fury.io/rb/next_page)
+[![RuboCop](https://github.com/RockSolt/next_page/workflows/RuboCop/badge.svg)](https://github.com/RockSolt/next_page/actions?query=workflow%3ARuboCop)
+
 # NextPage
 Basic pagination for Rails controllers.
 
@@ -43,6 +46,18 @@ resource:
 @photos = paginate_resource(@photos)
 ```
 
+### Sorting
+Requests can specify sort order using the parameter `sort` with an attribute name, scope, or nested attribute. Attributes and nested attributes can be prefixed with `+` or `-` to indicate ascending or descending. Multiple sorts can be specified either as a comma separated list or via bracket notation.
+
+    /photos?sort=-created_at
+    /photos?sort=location,-created_by
+    /photos?sort[]=location&photos[]=-created_by
+
+The default sort order is primary key descending. It can be overridden by using the `default_sort` option of `paginate_with`. Use a string formatted just as url parameter would be formatted.
+
+```ruby
+paginate_with default_sort: '-created_at'
+```
 
 ### Default Limit
 The default size limit can be overridden with the `paginate_with` method for either type of paginagion. Pass option
@@ -60,12 +75,18 @@ paginate_with default_limit: 12, instance_variable_name: 'data'
 ```
 
 ### Link Helpers
-This gem does not do any rendering. It does provide helper methods for generating links. The resource will include the following additional methods:
+This gem does not do any rendering. It does provide helper methods for generating links. The resource will include the following additional methods (when the request header Accept is `'application/vnd.api+json'`):
 - current_page
 - next_page
 - total_pages
 - per_page
 
+#### Count Query
+In some cases (such as grouping), calling count on the query does not provide an accurate representation. If that is the case, then there are two ways to override the default behavior:
+- provide a count_query that can resolve the attributes
+- specify the following attributes manually: current_page, total_count, and per_page
+
+
 ## Installation
 Add this line to your application's Gemfile:
 

data/lib/next_page.rb

@@ -1,7 +1,9 @@
 # frozen_string_literal: true
 
+require 'next_page/exceptions'
 require 'next_page/pagination'
 require 'next_page/pagination_attributes'
+require 'next_page/sorter'
 require 'next_page/paginator'
 
 # = Next Page

data/lib/next_page/exceptions.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module NextPage
+  module Exceptions
+    class NextPageError < StandardError
+    end
+  end
+end
+
+require 'next_page/exceptions/invalid_nested_sort'
+require 'next_page/exceptions/invalid_sort_parameter'

data/lib/next_page/exceptions/invalid_nested_sort.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module NextPage
+  module Exceptions
+    # = Invalid Nested Sort
+    class InvalidNestedSort < NextPage::Exceptions::NextPageError
+      def initialize(model, association)
+        @model = model
+        @association = association
+      end
+
+      def message
+        "Invalid nested sort: Unable to find association #{@association} on model #{@model}"
+      end
+    end
+  end
+end

data/lib/next_page/exceptions/invalid_sort_parameter.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module NextPage
+  module Exceptions
+    # = Invalid Sort Parameter
+    class InvalidSortParameter < NextPage::Exceptions::NextPageError
+      def initialize(segment)
+        @segment = segment
+      end
+
+      def message
+        "Invalid sort parameter (#{@segment}). Must be an attribute or scope."
+      end
+    end
+  end
+end

data/lib/next_page/pagination.rb

@@ -52,28 +52,28 @@ module NextPage
       # - instance_variable_name: explicitly name the variable if it does not follow the convention
       # - model_class: explicitly specify the model name if it does not follow the convention
       # - default_limit: specify an alternate default
-      def paginate_with(instance_variable_name: nil, model_class: nil, default_limit: nil)
-        next_page_paginator.paginate_with(instance_variable_name, model_class, default_limit)
+      # - default_sort: sort parameter if none provided, use same format as url: created_at OR -updated_at
+      def paginate_with(instance_variable_name: nil, model_class: nil, default_limit: nil, default_sort: nil)
+        next_page_paginator.paginate_with(instance_variable_name, model_class, default_limit, default_sort)
       end
     end
 
     # Called with before_action in order to automatically paginate the resource.
     def apply_next_page_pagination
-      self.class.next_page_paginator.paginate(self, params[:page])
+      self.class.next_page_paginator.paginate(self, params.slice(:page, :sort))
     end
 
     # Invokes pagination directly, the result must be stored as the resource itself is not modified.
     def paginate_resource(resource)
-      self.class.next_page_paginator.paginate_resource(resource, params[:page])
+      self.class.next_page_paginator.paginate_resource(resource, params.slice(:page, :sort))
     end
 
     def render(*args) #:nodoc:
       return super unless action_name == 'index' && request.headers[:Accept] == 'application/vnd.api+json'
 
-      options = args.first
-      return super unless options.is_a?(Hash) && options.key?(:json)
-
-      options[:meta] = options.fetch(:meta, {}).merge!(total_pages: options[:json].total_pages)
+      self.class.next_page_paginator.decorate_meta!(args.first)
+      super
+    rescue StandardError
       super
     end
   end

data/lib/next_page/pagination_attributes.rb

@@ -5,21 +5,36 @@ module NextPage
   #
   # Module PaginationAttributes adds in methods required for pagination links: current_page, next_page, and total_pages.
   # It reads the offset and limit on the query to determine the values.
+  #
+  # In some cases the query will not support count. In that case, there are two ways to override the default behavior:
+  # - provide a count_query that can resolve the attributes
+  # - specify the following attributes manually: current_page, total_count, and per_page
   module PaginationAttributes
+    attr_writer :count_query, :current_page, :total_count, :per_page
+
     def current_page
-      @current_page ||= offset_value + 1
+      @current_page ||= count_query.offset_value + 1
     end
 
     def next_page
       current_page + 1
     end
 
+    def total_count
+      @total_count ||= count_query.unscope(:limit).unscope(:offset).count
+    end
+
     def total_pages
-      @total_pages ||= unscope(:limit).unscope(:offset).count / per_page
+      total_count.fdiv(per_page).ceil
     end
 
     def per_page
-      @per_page ||= limit_value
+      @per_page ||= count_query.limit_value
+    end
+
+    # checks first to see if an override query has been provided, then fails back to self
+    def count_query
+      @count_query || self
     end
   end
 end

data/lib/next_page/paginator.rb

@@ -22,10 +22,11 @@ module NextPage
       @default_limit = DEFAULT_LIMIT
     end
 
-    def paginate_with(instance_variable_name, model_class, default_limit)
+    def paginate_with(instance_variable_name, model_class, default_limit, default_sort)
       @default_limit = default_limit if default_limit.present?
       @instance_variable_name = instance_variable_name
       @model_class = model_class.is_a?(String) ? model_class.constantize : model_class
+      @default_sort = default_sort
     end
 
     def paginate(controller, page_params)
@@ -35,12 +36,19 @@ module NextPage
       controller.instance_variable_set(name, paginate_resource(data, page_params))
     end
 
-    def paginate_resource(data, page_params)
-      data.extend(NextPage::PaginationAttributes)
+    def paginate_resource(data, params)
+      assign_pagination_attributes(data, params)
+
+      data = sorter.sort(data, params.fetch(:sort, default_sort))
+      data.limit(data.per_page).offset((data.current_page - 1) * data.per_page)
+    end
 
-      limit = page_size(page_params)
-      offset = page_number(page_params) - 1
-      data.limit(limit).offset(offset * limit)
+    def decorate_meta!(options)
+      return unless options.is_a?(Hash) && options.key?(:json) && !options[:json].is_a?(Hash)
+
+      resource = options[:json]
+      options[:meta] = options.fetch(:meta, {}).merge!(total_pages: resource.total_pages,
+                                                       total_count: resource.total_count)
     end
 
     private
@@ -55,6 +63,16 @@ module NextPage
       @instance_variable_name ||= @controller_name
     end
 
+    def default_sort
+      @default_sort ||= "-#{@model_class.primary_key}"
+    end
+
+    def assign_pagination_attributes(data, params)
+      data.extend(NextPage::PaginationAttributes)
+      data.per_page = page_size(params[:page])
+      data.current_page = page_number(params[:page])
+    end
+
     def page_size(page)
       if page.present? && page[:size].present?
         page[:size]&.to_i
@@ -70,5 +88,9 @@ module NextPage
         1
       end
     end
+
+    def sorter
+      @sorter ||= NextPage::Sorter.new(model_class)
+    end
   end
 end

data/lib/next_page/sorter.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module NextPage
+  # = Sorter
+  #
+  # Class Sorter reads the sort parameter and applies the related ordering. Results for each parameter string are
+  # cached so evaluation only occurs once.
+  class Sorter
+    SEGMENT_REGEX = /(?<sign>[+|-]?)(?<attribute>\w+)/.freeze
+
+    # Initializes a new sorter. The given model is used to validate sort attributes as well as build nested sorts.
+    def initialize(model)
+      @model = model
+      @cache = Hash.new { |hash, key| hash[key] = build_sort(key) }
+    end
+
+    # Adds sorting to given query based upon the param. Returns a new query; the existing query is NOT modified.
+    #
+    # The +query+ parameter is an ActiveRecord arel or model.
+    #
+    # The +sort_fields+ parameter is a string that conforms to the JSON-API specification for sorting fields:
+    # https://jsonapi.org/format/#fetching-sorting
+    def sort(query, sort_fields)
+      return from_array(query, sort_fields.split(',')) if sort_fields.include?(',')
+      return from_array(query, sort_fields) if sort_fields.is_a? Array
+
+      apply_sort(query, sort_fields)
+    end
+
+    private
+
+    def apply_sort(query, key)
+      @cache[key].call(query)
+    end
+
+    def from_array(query, param)
+      param.reduce(query) { |memo, key| apply_sort(memo, key) }
+    end
+
+    # returns a lambda that applies the appropriate sort, either from a scope, nested attribute, or attribute
+    def build_sort(key)
+      ActiveSupport::Notifications.instrument('build_sort.next_page', { key: key }) do
+        if @model.respond_to?(key)
+          ->(query) { query.send(key) }
+        elsif key.include?('.')
+          build_nested_sort(key)
+        else
+          order_params = directional_attribute(@model, key)
+          ->(query) { query.order(order_params) }
+        end
+      end
+    end
+
+    def build_nested_sort(nested_key)
+      # remove and capture sign if present
+      sign = nil
+      if nested_key.start_with?('+', '-')
+        sign = nested_key[0]
+        nested_key = nested_key[1..-1]
+      end
+
+      *associations, key = *nested_key.split('.')
+      sort_model = dig_association_model(associations)
+      joins = build_joins(associations)
+      order_params = directional_attribute(sort_model, "#{sign}#{key}")
+
+      ->(query) { query.joins(joins).merge(sort_model.order(order_params)) }
+    end
+
+    # traverse nested associations to find last association's model
+    def dig_association_model(associations)
+      associations.reduce(@model) do |model, association_name|
+        association = model.reflect_on_association(association_name)
+        raise NextPage::Exceptions::InvalidNestedSort.new(model, association_name) if association.nil?
+
+        association.klass
+      end
+    end
+
+    # transform associations array to nested hash
+    # ['team'] => [:team]
+    # ['team', 'coach'] => { team: :coach }
+    def build_joins(associations)
+      associations.map(&:to_sym)
+                  .reverse
+                  .reduce { |memo, association| memo.nil? ? association.to_sym : { association => memo } }
+    end
+
+    def directional_attribute(model, segment)
+      parsed = segment.match SEGMENT_REGEX
+      attribute = parsed['attribute']
+      direction = parsed['sign'] == '-' ? 'desc' : 'asc'
+      return { attribute => direction } if model.attribute_names.include?(attribute)
+
+      raise NextPage::Exceptions::InvalidSortParameter, segment
+    end
+  end
+end

data/lib/next_page/version.rb

@@ -1,3 +1,3 @@
 module NextPage
-  VERSION = '0.1.1'
+  VERSION = '0.1.6'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: next_page
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.6
 platform: ruby
 authors:
 - Todd Kummer
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-04 00:00:00.000000000 Z
+date: 2020-07-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -106,14 +106,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.77'
+        version: 0.82.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.77'
+        version: 0.82.0
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
@@ -140,16 +140,20 @@ files:
 - README.md
 - Rakefile
 - lib/next_page.rb
+- lib/next_page/exceptions.rb
+- lib/next_page/exceptions/invalid_nested_sort.rb
+- lib/next_page/exceptions/invalid_sort_parameter.rb
 - lib/next_page/pagination.rb
 - lib/next_page/pagination_attributes.rb
 - lib/next_page/paginator.rb
+- lib/next_page/sorter.rb
 - lib/next_page/version.rb
 - lib/tasks/next_page_tasks.rake
 homepage: https://github.com/RockSolt/next_page
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -165,7 +169,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.0.8
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Pagination for Rails Controllers
 test_files: []