next_page 0.1.2 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 423a7c89235a411543d5c3a70cdedc6c09cca6af9d2039de6fe87dbbfe73bad9
-  data.tar.gz: '09cac0c988dc7730d5899aa1ecf0fb4d7663225cbf036bc1161634531f0cca7e'
+  metadata.gz: 91b9a69827f83cb0e3fd5dcbbdab8537c61d859f89cea744a2afccf8afcf3570
+  data.tar.gz: 4474b5cdb0d3e44473df17a0ae10fbd389abf9a3e372062f5691fb656c8a21e4
 SHA512:
-  metadata.gz: e5926d53cbe7ce204259be7a100a683f84c37044238033e5d582e636b5d07d5de84edea27d7a80e512bc186d8d85f277dd5a8574cc11d278a28062ecd8900662
-  data.tar.gz: 1fac9c2164eafa53ed179d1dca474b6b63b0873d58c9983fa38c86d00f7ef40a07a52916097a20e2f1528c9a6c7b620d9cd7c7426b1d67e37e4c22f304143e77
+  metadata.gz: bf4b093bb8ae31e75c83416539bd3b9848956e81ff90fcecfd0ed90c08cfdbaf6f84e55651130f6115b3c070f77c0d46a336ce95e74bd785f8a0cd20b5d6dba6
+  data.tar.gz: b0d3559fc5db3431acf8102471db073e17fc428bd8bfc05bbf1b8f472547d4686b9da0eaed4872e9313b0c3d2600ae58f28b933b23732646d3027c1206fd3ac0

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,53 @@ resource:
 @photos = paginate_resource(@photos)
 ```
 
+### Sorting
+Requests can specify sort order using the parameter `sort` with an attribute name or scope. Sorts 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'
+```
+
+#### Nested Sorts
+
+Nested attributes and scopes can be indicated by providing the association names separated by periods.
+
+    /photos?sort=user.name
+    /photos?sort=-user.address.state
+
+#### Directional Scope Sorts
+
+In order to use directions (`+` or `-`) with a scope, the scope must be defined as a class method and take a single parameter. The scope will receive either `'asc'` or `'desc'`. Here is an example of a valid directional scope.
+
+```ruby
+def self.status(direction)
+  order("CASE status WHEN 'new' THEN 1 WHEN 'in progress' THEN 2 ELSE 3 END #{direction}")
+end
+```
+
+#### Scope Prefix / Suffix
+
+In order to keep the peace between frontend and backend developers, scope names can include a prefix or suffix that the front end can ignore. For example, given a scope that sorts on a derived attribute (such as status in the _Direction Scope Sorts_ example), the backend developer might prefer to name the scope status_sort or sort_by_status, as a class method that shares the same name as an attribute might be unclear. However, the frontend developer does not want a query parameter that says <tt>sort=sort_by_status</tt>; it is an exception because it doesn't match the name of the attribute (and it's not pretty).
+
+The configuration allows a prefix and or suffix to be specified. If either is specified, then in addition to looking for a scope that matches the parameter name, it will also look for a scope that matches the prefixed and/or suffixed name. Prefixes are defined by configuration option <tt>sort_scope_prefix</tt> and suffixes are defined by <tt>sort_scope_suffix</tt>.
+
+For example, if the backend developer prefers <tt>sort_by_status</tt> then the following configuration can be used:
+
+```ruby
+NextPage.configure do |config|
+  config.sort_scope_prefix = 'sort_by_'
+end
+``` 
+This allows the query parameter to be the following:
+
+    sort=status
+
 
 ### Default Limit
 The default size limit can be overridden with the `paginate_with` method for either type of paginagion. Pass option
@@ -60,12 +110,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,9 +1,27 @@
 # frozen_string_literal: true
 
+require 'next_page/configuration'
+require 'next_page/exceptions'
 require 'next_page/pagination'
 require 'next_page/pagination_attributes'
+require 'next_page/sorter'
 require 'next_page/paginator'
 
 # = Next Page
 module NextPage
+  class << self
+    attr_writer :configuration
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.reset
+    @configuration = Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
 end

data/lib/next_page/configuration.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module NextPage
+  # = Configuration
+  #
+  # Class Configuration stores the following settings:
+  # - sort_scope_prefix
+  # - sort_scope_suffix
+  #
+  # == Sort Scope Prefix
+  # Enables client to sort request to be mapped to a scope with a more specific name. For example, given a derived
+  # attribute named <tt>status</tt>, the query parameter can be <tt>sort=status</tt> but would map to a more explicitly
+  # named scope, such as <tt>sort_by_status</tt> (assuming the <tt>sort_scope_prefix</tt> value is 'sort_by_').
+  #
+  # == Sort Scope Suffix
+  # Enables client to sort request to be mapped to a scope with a more specific name. For example, given a derived
+  # attribute named <tt>status</tt>, the query parameter can be <tt>sort=status</tt> but would map to a more explicitly
+  # named scope, such as <tt>status_sort</tt> (assuming the <tt>sort_scope_suffix</tt> value is '_sort').
+  class Configuration
+    attr_reader :sort_scope_prefix, :sort_scope_suffix
+
+    def sort_scope_prefix=(value)
+      @sort_scope_prefix = value.to_s
+    end
+
+    def sort_scope_prefix?
+      @sort_scope_prefix.present?
+    end
+
+    def sort_scope_suffix=(value)
+      @sort_scope_suffix = value.to_s
+    end
+
+    def sort_scope_suffix?
+      @sort_scope_suffix.present?
+    end
+  end
+end

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,9 +5,15 @@ 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
@@ -15,7 +21,7 @@ module NextPage
     end
 
     def total_count
-      @total_count ||= unscope(:limit).unscope(:offset).count
+      @total_count ||= count_query.unscope(:limit).unscope(:offset).count
     end
 
     def total_pages
@@ -23,7 +29,12 @@ module NextPage
     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/sort/name_evaluator.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module NextPage
+  module Sort
+    # = Name Evaluator
+    #
+    # Determines if a name represents an attribute or a scope, provides mapping if the scope requires a prefix or
+    # suffix. Scope is checked first, allowing it to override an attribute of the same name. For scopes, method
+    # <tt>directional_scope?</tt> checks to see if the scope is a class method that accepts one parameter; if so, then
+    # the scope will be invoked with the direction.
+    class NameEvaluator
+      attr_reader :scope_name
+
+      def initialize(model, name)
+        @model = model
+        @name = name.to_s
+        evaluate_for_scope
+      end
+
+      def scope?
+        @scope_name.present?
+      end
+
+      # true when scope is class method with one parameter
+      def directional_scope?
+        return false unless scope?
+
+        @model.method(@scope_name).arity == 1
+      end
+
+      def valid_attribute_name?
+        @model.attribute_names.include?(@name)
+      end
+
+      private
+
+      def evaluate_for_scope
+        assign_scope(@name) || assign_prefixed_scope || assign_suffixed_scope
+      end
+
+      def assign_scope(potential_scope)
+        return if @model.dangerous_class_method?(potential_scope) || !@model.respond_to?(potential_scope)
+
+        @scope_name = potential_scope
+      end
+
+      def assign_prefixed_scope
+        return unless NextPage.configuration.sort_scope_prefix?
+
+        assign_scope("#{NextPage.configuration.sort_scope_prefix}#{@name}")
+      end
+
+      def assign_suffixed_scope
+        return unless NextPage.configuration.sort_scope_suffix?
+
+        assign_scope("#{@name}#{NextPage.configuration.sort_scope_suffix}")
+      end
+    end
+  end
+end

data/lib/next_page/sort/segment_parser.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module NextPage
+  module Sort
+    # = Segment Parser
+    #
+    # Parses each sort segment to provide direction, associations, and name.
+    class SegmentParser
+      attr_reader :direction, :associations, :name
+
+      SEGMENT_REGEX = /(?<sign>[+|-]?)(?<names>.+)/.freeze
+
+      def initialize(segment)
+        @segment = segment
+        parsed = segment.match SEGMENT_REGEX
+        @direction = parsed['sign'] == '-' ? 'desc' : 'asc'
+        *@associations, @name = *parsed['names'].split('.')
+      end
+
+      def to_s
+        @segment
+      end
+
+      def attribute_with_direction
+        { @name => @direction }
+      end
+
+      def nested?
+        @associations.present?
+      end
+    end
+  end
+end

data/lib/next_page/sort/sort_builder.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module NextPage
+  module Sort
+    # = Sort Builder
+    class SortBuilder
+      def initialize(model)
+        @model = model
+      end
+
+      # TODO: support passing direction to scope
+      def build(segment)
+        @parser = NextPage::Sort::SegmentParser.new(segment)
+
+        if @parser.nested?
+          build_nested
+        else
+          build_non_nested
+        end
+      end
+
+      private
+
+      def build_nested
+        sort_model = dig_association_model(@parser.associations)
+        joins = build_joins(@parser.associations)
+        evaluator = NextPage::Sort::NameEvaluator.new(sort_model, @parser.name)
+
+        if evaluator.scope?
+          build_nested_scope_sort(sort_model, joins, evaluator)
+        elsif evaluator.valid_attribute_name?
+          nested_attribute_sort(sort_model, joins, @parser.attribute_with_direction)
+        else
+          raise NextPage::Exceptions::InvalidSortParameter, @parser
+        end
+      end
+
+      def build_nested_scope_sort(sort_model, joins, evaluator)
+        if evaluator.directional_scope?
+          nested_directional_scope_sort(sort_model, joins, evaluator.scope_name, @parser.direction)
+        else
+          nested_scope_sort(sort_model, joins, evaluator.scope_name)
+        end
+      end
+
+      def nested_attribute_sort(model, joins, attribute_with_direction)
+        ->(query) { query.joins(joins).merge(model.order(attribute_with_direction)) }
+      end
+
+      def nested_scope_sort(model, joins, scope_name)
+        ->(query) { query.joins(joins).merge(model.public_send(scope_name)) }
+      end
+
+      def nested_directional_scope_sort(model, joins, scope_name, direction)
+        ->(query) { query.joins(joins).merge(model.public_send(scope_name, direction)) }
+      end
+
+      def build_non_nested
+        evaluator = NextPage::Sort::NameEvaluator.new(@model, @parser.name)
+
+        if evaluator.scope?
+          build_non_nested_scope_sort(evaluator)
+        elsif evaluator.valid_attribute_name?
+          attribute_sort(@parser.attribute_with_direction)
+        else
+          raise NextPage::Exceptions::InvalidSortParameter, @parser
+        end
+      end
+
+      def build_non_nested_scope_sort(evaluator)
+        if evaluator.directional_scope?
+          directional_scope_sort(evaluator.scope_name, @parser.direction)
+        else
+          scope_sort(evaluator.scope_name)
+        end
+      end
+
+      def attribute_sort(attribute_with_direction)
+        ->(query) { query.order(attribute_with_direction) }
+      end
+
+      def scope_sort(scope_name)
+        ->(query) { query.send(scope_name) }
+      end
+
+      def directional_scope_sort(scope_name, direction)
+        ->(query) { query.send(scope_name, direction) }
+      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
+
+      # TODO: consider prefix / suffix
+      def named_scope(sort_model)
+        # checking dangerous_class_method? excludes any names that cannot be scope names, such as "name"
+        return unless sort_model.respond_to?(@parser.name) && !sort_model.dangerous_class_method?(@parser.name)
+
+        @parser.name
+      end
+    end
+  end
+end

data/lib/next_page/sorter.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'next_page/sort/name_evaluator'
+require 'next_page/sort/segment_parser'
+require 'next_page/sort/sort_builder'
+
+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
+    # 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
+        NextPage::Sort::SortBuilder.new(@model).build(key)
+      end
+    end
+  end
+end

data/lib/next_page/version.rb

@@ -1,3 +1,3 @@
 module NextPage
-  VERSION = '0.1.2'
+  VERSION = '0.1.7'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: next_page
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.7
 platform: ruby
 authors:
 - Todd Kummer
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-05-05 00:00:00.000000000 Z
+date: 2020-08-12 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,24 @@ files:
 - README.md
 - Rakefile
 - lib/next_page.rb
+- lib/next_page/configuration.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/sort/name_evaluator.rb
+- lib/next_page/sort/segment_parser.rb
+- lib/next_page/sort/sort_builder.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 +173,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: []