next_page 0.1.6 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48258d40caac39b331bba8d81ea99fcbb5523bab818616243149a952c4c286ea
-  data.tar.gz: b52465382e154b636c18f1b0c881cc3c5a4908aa4410a959fe4696904764846b
+  metadata.gz: 91b9a69827f83cb0e3fd5dcbbdab8537c61d859f89cea744a2afccf8afcf3570
+  data.tar.gz: 4474b5cdb0d3e44473df17a0ae10fbd389abf9a3e372062f5691fb656c8a21e4
 SHA512:
-  metadata.gz: ecdb889ce15846cda3025f6d8c07f61e2901c7633e191c88b8c9aedea79105fd639d95e9abbed8f1cfed8be98ab885f7be4cd67cf5d87d451812e93cceb929b6
-  data.tar.gz: 3a1aea4f5ca07e1656e61bc89a4cae38cfb0fe9523d26a7fb5a3064661e87c06c1c1f811fd3191b5f262b5186eabf38e3a40414064d4c1d3eb5bd56d10bb7704
+  metadata.gz: bf4b093bb8ae31e75c83416539bd3b9848956e81ff90fcecfd0ed90c08cfdbaf6f84e55651130f6115b3c070f77c0d46a336ce95e74bd785f8a0cd20b5d6dba6
+  data.tar.gz: b0d3559fc5db3431acf8102471db073e17fc428bd8bfc05bbf1b8f472547d4686b9da0eaed4872e9313b0c3d2600ae58f28b933b23732646d3027c1206fd3ac0

data/README.md

@@ -47,7 +47,7 @@ resource:
 ```
 
 ### 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.
+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
@@ -59,6 +59,41 @@ The default sort order is primary key descending. It can be overridden by using
 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
 `default_limit` to specify an override:

data/lib/next_page.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'next_page/configuration'
 require 'next_page/exceptions'
 require 'next_page/pagination'
 require 'next_page/pagination_attributes'
@@ -8,4 +9,19 @@ 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/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

@@ -1,13 +1,15 @@
 # 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
-    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
@@ -40,59 +42,8 @@ module NextPage
     # 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
+        NextPage::Sort::SortBuilder.new(@model).build(key)
       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.6'
+  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.6
+  version: 0.1.7
 platform: ruby
 authors:
 - Todd Kummer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-07-01 00:00:00.000000000 Z
+date: 2020-08-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -140,12 +140,16 @@ 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