next_page 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 816ed22df71f4838cfe99457bec6a62c2b0e01318436a1fa8f03eb927dfb8939
-  data.tar.gz: 170578dcc7f6ee852c461fb43597bc0d3a64231016c74498ad674da847296690
+  metadata.gz: 38c9e0beeee5d1e9d2e9a4a85e25fdf5011c6d9116dcb35ffdaaddfa795a3cca
+  data.tar.gz: 408c859f1330a3ce2a577d43f8af4bbf390031d4a5aca33c1a40f7d2ba29465b
 SHA512:
-  metadata.gz: 47b95e0134da9e2ff7032e35ca485d0da63fd2c84c8959833e7e1f6338879968d20458ed244553d60d9406a5880f4f8216ad8e5a218b047fcb27fdf113d65a51
-  data.tar.gz: 5860bb0ce08448a20625d051bdae952c45a04310a46b10de82d0a758cc0812b4b14e688a9d2732f68a2c11b973d99f08eaf59a7a8da283bf91788c96830fbf9c
+  metadata.gz: b2ef11040267561b0daf6174b766c374b998a3effe8c2de9e76b13980386d98bb3b4562e2858a3e70a700a2d45154f6dcd381951dbc997f20af1c99d9435b98e
+  data.tar.gz: 7267d87c88104d59d007b6b986fd398853f2591a2b87c25293986fa0fd5559dd7bc08bca4b0a33683f34656165ac3b6490a86d86c7d0f2d647950d558da6dc56

data/README.md

@@ -4,43 +4,72 @@
 [![Maintainability](https://api.codeclimate.com/v1/badges/0efe1a9b66a0bf161536/maintainability)](https://codeclimate.com/github/RockSolt/next_page/maintainability)
 
 # NextPage
-Basic pagination for Rails controllers.
 
-## Usage
-Module Pagination provides pagination for index methods. It assigns a limit and offset to the resource query and extends the relation with mixin NextPage::PaginationAttributes to provide helper methods for generating links.
+NextPage provides simple pagination with no frills in less than 100 lines of code. It reads request
+parameters, provides an offset and limit to the query, and decorates the ActiveRecord relation
+with pagination attributes. 
 
-### Include the Module
-Add an include statement for the module into any controller that needs pagination:
+No more, no less.
 
-```ruby
-include NextPage::Pagination
 ```
+def index
+  @widgets = paginate_resource(Widget.all)
+end
+```
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Usage](#usage)
+  - [Include the Module](#include-the-module)
+  - [Invoking Pagination](#invoking-pagination)
+  - [Link Helpers](#link-helpers)
+    - [Count Query](#count-query)
+  - [Request Parameters](#request-parameters)
+  - [Default Results per Action](#default-results-per-action)
+- [Configuration](#configuration)
+- [Contribute](#contribute)
+  - [Running Tests](#running-tests)
+- [License](#license)
 
-There are two ways to paginate: using a before filter or by calling `paginate_resource` explicitly.
+## Getting Started
 
-### Before Filter
-Here's an example of using the before filter in a controller:
+This gem requires Rails 7.1+ and works with ActiveRecord.
+
+### Installation
+
+Add this line to your application's Gemfile:
 
 ```ruby
-before_action :apply_next_page_pagination, only: :index
+gem 'next_page'
 ```
 
-This entry point uses the following conventions to apply pagination:
-- the name of the instance variable is the sames as the component (for example PhotosController -> @photos)
-- the name of the models is the controller name singularized (for example PhotosController -> Photo)
+And then execute:
+```bash
+$ bundle
+```
 
-Either can be overridden by calling method `paginate_with` in the controller. The two override options are
-`instance_variable_name` and `model_class`. For example, if the PhotosController used the model Picture and the
-instance variable name @photographs, the controller declares it as follows:
+Or install it yourself as:
+```bash
+$ gem install next_page
+```
+
+## Usage
+
+Module NextPage::Pagination provides pagination controllers. It assigns a limit and offset to the 
+resource query and extends the relation with mixin NextPage::PaginationAttributes to provide helper 
+methods for generating links.
+
+### Include the Module
+
+Add an include statement for the module into any controller that needs pagination (or the ApplicationController):
 
 ```ruby
-paginate_with instance_variable_name: :photographs, model_class: 'Picture'
+include NextPage::Pagination
 ```
 
-If the before filter is used, it will populate an instance variable. The action should NOT reset the variable, as
-that removes pagination.
+### Invoking Pagination
 
-### Invoking Pagination Directly
 To paginate a resource pass the resource into method `paginate_resource` then store the return value back in the
 resource:
 
@@ -48,98 +77,82 @@ 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 resource is decorated, so this needs to be the last step before rendering.
 
-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.
+### Link Helpers
 
-```ruby
-paginate_with default_sort: '-created_at'
-```
+This gem does not do any rendering. It does provide helper methods for generating links. The resource will include the following additional methods:
+- previous_page
+- current_page
+- next_page
+- total_pages
+- total_count
+- per_page
 
-#### Nested Sorts
+The `previous_page` and `last_page` readers will return `nil` on the first and last page, respectively.
 
-Nested attributes and scopes can be indicated by providing the association names separated by periods.
+#### Count Query
 
-    /photos?sort=user.name
-    /photos?sort=-user.address.state
+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
 
-#### Directional Scope Sorts
+### Request Parameters
 
-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.
+In order to control pagingation, the request should pass the `size` and `number` parameters under the
+`page` key:
 
-```ruby
-def self.status(direction)
-  order("CASE status WHEN 'new' THEN 1 WHEN 'in progress' THEN 2 ELSE 3 END #{direction}")
-end
+```
+?page[size]=10&page[number]=2
 ```
 
-#### 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>.
+### Default Results per Action
 
-For example, if the backend developer prefers <tt>sort_by_status</tt> then the following configuration can be used:
+The default number of results per page can be overridden by specifying a new default with the call:
 
 ```ruby
-NextPage.configure do |config|
-  config.sort_scope_prefix = 'sort_by_'
-end
-``` 
-This allows the query parameter to be the following:
+@photos = paginate_resource(@photos, default_limit: 25)
+```
 
-    sort=status
+## Configuration
 
+There is one configuration option: `default_per_page`.
 
-### 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:
+The option can be set directly...
 
-```ruby
-paginate_with default_limit: 25
-```
+`NextPage.configuration.default_per_page = 25`
 
-All the options can be mixed and matches when calling `paginate_with`:
+...or the configuration can be yielded:
 
-```ruby
-paginate_with model_class: 'Photo', default_limit: 12
-paginate_with default_limit: 12, instance_variable_name: 'data'
+```
+NextPage.configure do |config|
+  config.default_per_page = 25
+end
 ```
 
-### 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 (when the request header Accept is `'application/vnd.api+json'`):
-- current_page
-- next_page
-- total_pages
-- per_page
+**Results 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
+If not specified in the configuration, the default value for results per page is 12.
 
+## Contribute
 
-## Installation
-Add this line to your application's Gemfile:
+Feedback, feature requests, proposed changes, and bug reports are welcomed. Please use the 
+[issue tracker](https://github.com/RockSolt/next_page/issues) for feedback and feature requests. To 
+propose a change directly, please fork the repo and open a pull request. Keep an eye on the actions 
+to make sure the tests and Rubocop are passing. [Code Climate](https://codeclimate.com/github/RockSolt/next_page)
+is also used manually to assess the codeline.
 
-```ruby
-gem 'next_page'
-```
+### Running Tests
 
-And then execute:
-```bash
-$ bundle
-```
+Tests are written in RSpec and the dummy app uses a docker database. 
+
+The tests can also be run across all the ruby and Rails combinations using appraisal. The install is a one-time step.
 
-Or install it yourself as:
 ```bash
-$ gem install next_page
+bundle exec appraisal install
+bundle exec appraisal rspec
 ```
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/next_page/configuration.rb

@@ -1,38 +1,15 @@
 # frozen_string_literal: true
 
 module NextPage
-  # = Configuration
+  # # 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').
+  # - default_per_page
   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
+    attr_accessor :default_per_page
 
-    def sort_scope_suffix?
-      @sort_scope_suffix.present?
+    def initialize
+      @default_per_page = 12
     end
   end
 end

data/lib/next_page/pagination.rb

@@ -1,80 +1,30 @@
 # frozen_string_literal: true
 
 module NextPage
-  # = Pagination
+  # # Pagination
   #
-  # Module Pagination provides pagination for index methods. It assigns a limit and offset
+  # Module Pagination provides pagination for ActiveRecord queries. It assigns a limit and offset
   # to the resource query and extends the relation with mixin NextPage::PaginationAttributes.
   #
-  # There are two ways to paginate: using a before filter or by calling `paginate_resource` explicitly.
   #
-  # == Before Filter
-  # Here's an example of using the before filter in a controller:
-  #   before_action :apply_next_page_pagination, only: :index
+  # ## Invoking Pagination
   #
-  # This entry point uses the following conventions to apply pagination:
-  # - the name of the instance variable is the same as the component (for example PhotosController -> @photos)
-  # - the name of the model is the controller name singularized (for example PhotosController -> Photo)
-  #
-  # Either can be overridden by calling method `paginate_with` in the controller. The two override options are
-  # `instance_variable_name` and `model_class`. For example, if the PhotosController used the model Picture and the
-  # instance variable name @photographs, the controller declares it as follows:
-  #   paginate_with instance_variable_name: :photographs, model_class: 'Picture'
-  #
-  # If the before filter is used, it will populate an instance variable. The action should NOT reset the variable, as
-  # that removes pagination.
-  #
-  # == Invoking Pagination Directly
   # To paginate a resource pass the resource into method `paginate_resource` then store the return value back in the
   # resource:
   #
   #   @photos = paginate_resource(@photos)
   #
-  # == Default Limit
-  # The default size limit can be overridden with the `paginate_with` method for either type of pagination. Pass option
-  # `default_limit` to specify an override:
-  #
-  #   paginate_with default_limit: 25
-  #
-  # All the options can be mixed and matches when calling `paginate_with`:
-  #
-  #   paginate_with model_class: 'Photo', default_limit: 12
-  #   paginate_with default_limit: 12, instance_variable_name: 'data'
   module Pagination
     extend ActiveSupport::Concern
 
     class_methods do
       def next_page_paginator # :nodoc:
-        @next_page_paginator ||= NextPage::Paginator.new(controller_name, controller_path)
+        @next_page_paginator ||= NextPage::Paginator.new
       end
-
-      # Configure pagination with any of the following options:
-      # - 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
-      # - 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.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.slice(:page, :sort))
-    end
-
-    def render(*args) # :nodoc:
-      return super unless action_name == 'index' && request.headers[:Accept] == 'application/vnd.api+json'
-
-      self.class.next_page_paginator.decorate_meta!(args.first)
-      super
-    rescue StandardError
-      super
+    def paginate_resource(resource, default_limit: nil)
+      self.class.next_page_paginator.paginate_resource(resource, params.fetch(:page, {}), default_limit)
     end
   end
 end

data/lib/next_page/pagination_attributes.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 module NextPage
-  # = Pagination Attributes
+  # # Pagination Attributes
   #
-  # Module PaginationAttributes adds in methods required for pagination links: previous_page, current_page, next_page,
+  # Module PaginationAttributes adds in methods to help with pagination links: previous_page, 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
+  #
+  # These can be completed after the call to `paginate_resource`.
   module PaginationAttributes
     attr_writer :count_query, :current_page, :total_count, :per_page
 

data/lib/next_page/paginator.rb

@@ -1,96 +1,31 @@
 # frozen_string_literal: true
 
 module NextPage
-  # = Paginator
+  # # Paginator
   #
   # Class Paginator uses the controller information to determine the model and variable name for the
   # request, then applies a limit and offset to the query based upon the parameters or the defaults. It also extends
   # the resource with the NextPage::PaginationAttributes mixin.
-  #
-  # Configuration can be specified in the controller by calling `paginate_with`. The following overrides can be
-  # specified if necessary:
-  # - default_limit: limit to use if request does not specify (default value is 10)
-  # - instance_variable_name: default value is the controller name; for example, @photos in PhotosController
-  # - model_class: default derived from controller name (or path if nested); for example, Photo for PhotosController
   class Paginator
-    DEFAULT_LIMIT = 10
-
-    def initialize(controller_name, controller_path)
-      @controller_name = controller_name
-      @controller_path = controller_path
-
-      @default_limit = DEFAULT_LIMIT
-    end
-
-    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_resource(data, params, default_limit)
+      default_limit ||= NextPage.configuration.default_per_page
 
-    def paginate(controller, page_params)
-      name = "@#{instance_variable_name}"
-      data = controller.instance_variable_get(name) || model_class.all
+      assign_pagination_attributes(
+        data,
+        per_page: params[:size]&.to_i || default_limit,
+        current_page: params[:number]&.to_i || 1
+      )
 
-      controller.instance_variable_set(name, paginate_resource(data, page_params))
-    end
-
-    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
 
-    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
 
-    def model_class
-      @model_class ||= @controller_name.classify.safe_constantize ||
-                       @controller_path.classify.safe_constantize ||
-                       raise('Could not determine model for pagination; please specify using `paginate_with` options.')
-    end
-
-    def instance_variable_name
-      @instance_variable_name ||= @controller_name
-    end
-
-    def default_sort
-      @default_sort ||= "-#{@model_class.primary_key}"
-    end
-
-    def assign_pagination_attributes(data, params)
+    def assign_pagination_attributes(data, per_page:, current_page:)
       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
-      else
-        @default_limit
-      end
-    end
-
-    def page_number(page)
-      if page.present? && page[:number].present?
-        page[:number]&.to_i
-      else
-        1
-      end
-    end
 
-    def sorter
-      @sorter ||= NextPage::Sorter.new(model_class)
+      data.per_page = per_page
+      data.current_page = current_page
     end
   end
 end

data/lib/next_page/version.rb

@@ -1,3 +1,3 @@
 module NextPage
-  VERSION = '0.2.0'
+  VERSION = '1.0.0'.freeze
 end

data/lib/next_page.rb

@@ -1,18 +1,12 @@
 # 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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: next_page
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Todd Kummer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-21 00:00:00.000000000 Z
+date: 2025-04-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.7
+        version: 7.1.5
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.7
+        version: 7.1.5
 - !ruby/object:Gem::Dependency
   name: appraisal
   requirement: !ruby/object:Gem::Requirement
@@ -44,42 +44,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.18.0
+        version: '2.19'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 2.18.0
+        version: '2.19'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.7.3
+        version: '4.7'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 4.7.3
+        version: '4.7'
 - !ruby/object:Gem::Dependency
   name: guard-rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.5.0
+        version: '1.5'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.5.0
+        version: '1.5'
 - !ruby/object:Gem::Dependency
   name: pg
   requirement: !ruby/object:Gem::Requirement
@@ -100,42 +100,42 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.1.2
+        version: '7.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 5.1.2
+        version: '7.0'
 - !ruby/object:Gem::Dependency
   name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.60.1
+        version: '1.75'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.60.1
+        version: '1.75'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.19'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.18'
+        version: '0.19'
 description: Provide basic pagination, including page size and number as well as helpers
   for generating links.
 email:
@@ -149,18 +149,10 @@ files:
 - 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
@@ -173,14 +165,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.17
+rubygems_version: 3.5.7
 signing_key:
 specification_version: 4
 summary: Pagination for Rails Controllers

data/lib/next_page/exceptions/invalid_nested_sort.rb

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

data/lib/next_page/exceptions/invalid_sort_parameter.rb

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

data/lib/next_page/exceptions.rb

@@ -1,11 +0,0 @@
-# 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/sort/name_evaluator.rb

@@ -1,60 +0,0 @@
-# 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

@@ -1,33 +0,0 @@
-# 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>.+)/
-
-      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

@@ -1,118 +0,0 @@
-# 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,49 +0,0 @@
-# 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/tasks/next_page_tasks.rake

@@ -1,5 +0,0 @@
-# frozen_string_literal: true
-# desc "Explaining what the task does"
-# task :next_page do
-#   # Task goes here
-# end