next_page 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9789ab6b725aa655241fcfa9b43e66152b516a58b741088fd7797fe571a23915
-  data.tar.gz: da2e4c3608a52b1286ee33aef1005a5f4ab229fc579cd99b7c86c3177409423d
+  metadata.gz: fc0be3e3856dc94bd88845bc1d794eb179bc1b848c734e69788272075ec66f39
+  data.tar.gz: 3069427b0ac1cb6b91ff8ebc686d739805cb6adaadb6a85badf94843d9c5d13f
 SHA512:
-  metadata.gz: c7c72b0294f2f4f4f62208fa3fc9671fd67e342c09e37338ff1df6c9596ef09a935e4251a5d0ec9870aada9d451eb724efe2a213f6406d39e75baab1327b99fb
-  data.tar.gz: 9c8362bfcc1fa2694835fe30aa78afa43f957d7269bb0e2cad787cb452bb55582d36a064031061061640a55ff6553bd6f65c427cbe67c709b6be75eaf43997d7
+  metadata.gz: 74f6194348047238078e0b0fe3f5dd3a508b4a2d2a8e260511b19da571b40b187ea8fe79a363becf95f115945c1bedc4e79016bbf43d007ced9788e14924b1b8
+  data.tar.gz: 07db432a16ad366222ce3da4531203535e918be0562ce63c9a6d2fe852f1ad3f4dd90af8e53f2941428374abdfe2fa20397a11bfecc1f1d8633ab4a394fe83c1

data/README.md

@@ -43,6 +43,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

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,19 +52,20 @@ 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:

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,11 +36,13 @@ module NextPage
       controller.instance_variable_set(name, paginate_resource(data, page_params))
     end
 
-    def paginate_resource(data, page_params)
+    def paginate_resource(data, params)
       data.extend(NextPage::PaginationAttributes)
 
-      limit = page_size(page_params)
-      offset = page_number(page_params) - 1
+      data = sorter.sort(data, params.fetch(:sort, default_sort))
+
+      limit = page_size(params[:page])
+      offset = page_number(params[:page]) - 1
       data.limit(limit).offset(offset * limit)
     end
 
@@ -55,6 +58,10 @@ module NextPage
       @instance_variable_name ||= @controller_name
     end
 
+    def default_sort
+      @default_sort ||= "-#{@model_class.primary_key}"
+    end
+
     def page_size(page)
       if page.present? && page[:size].present?
         page[:size]&.to_i
@@ -70,5 +77,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.3'
+  VERSION = '0.1.4'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: next_page
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Todd Kummer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-05-05 00:00:00.000000000 Z
+date: 2020-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -140,9 +140,13 @@ 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