pagy 43.4.3 → 43.5.0

data/lib/pagy/classes/keyset/adapters/sequel.rb

@@ -3,9 +3,8 @@
 class Pagy
   class Keyset
     module Adapters
-      # Keyset adapter for sequel
+      # Keyset adapter for Sequel ORM
       module Sequel
-        # Extract the keyset from the set
         def extract_keyset
           return {} unless @set.opts[:order]
 
@@ -21,27 +20,26 @@ class Pagy
           end
         end
 
-        # Get the keyset attributes from a record
         def keyset_attributes_from(record)
           record.to_hash.slice(*@keyset.keys)
         end
 
-        # Get the hash of quoted keyset identifiers
         def quoted_identifiers(table)
           db = @set.db
           @keyset.to_h { |column| [column, "#{db.quote_identifier(table)}.#{db.quote_identifier(column)}"] }
         end
 
-        # Typecast the attributes
         def typecast(attributes)
-          model = @set.opts[:model]
-          model.unrestrict_primary_key if (primary_key_is_restricted = model.restrict_primary_key?)
-          attributes = model.new(attributes).to_hash.slice(*attributes.keys.map(&:to_sym))
-          model.restrict_primary_key if primary_key_is_restricted
-          attributes
+          model = @set.model
+          db    = @set.db
+          {}.tap do |result|
+            @keyset.each_key do |k|
+              type      = model.db_schema[k].fetch(:type)
+              result[k] = db.typecast_value(type, attributes[k])
+            end
+          end
         end
 
-        # Append the missing keyset keys, if the set is restricted by select
         def ensure_select
           return if @set.opts[:select].nil?
 
@@ -49,7 +47,6 @@ class Pagy
           @set = @set.select_append(*@keyset.keys.reject { |c| selected.include?(c) })
         end
 
-        # Apply the where predicate to the set
         def apply_where(predicate, arguments)
           @set = @set.where(::Sequel.lit(predicate, **arguments))
         end

data/lib/pagy/classes/keyset/keynav.rb

@@ -2,14 +2,13 @@
 
 class Pagy
   class Keyset
-    # Use keyset pagination with resources for all the frontend helpers
+    # Keyset pagination with broad UI support
     class Keynav < Keyset
       # Avoid conflicts between filter arguments in composite SQL fragments
       PRIOR_PREFIX = 'prior_'
       PAGE_PREFIX  = 'page_'
 
-      # Define empty subclasses to allow specific typing without triggering autoload.
-      # The .new factory in Keyset will handle mixing in the adapter logic from Pagy::Keyset::Adapters.
+      # Define empty subclasses to allow specific typing without triggering autoload
       class ActiveRecord < self; end
       class Sequel < self; end
 
@@ -18,8 +17,7 @@ class Pagy
       # Finalize the instance variables needed for the UI
       def initialize(set, **)
         super
-        # Ensure next is called, so the last page used by the UI helpers is known
-        self.next
+
         @previous = @page - 1 unless @page == 1
         @in       = @records.size
       end
@@ -31,7 +29,7 @@ class Pagy
       def next
         records
         @count = 0 if !@more && @page == 1  # empty records (trigger the right info message for known 0 count)
-        return if !@more || (@options[:max_pages] && @page >= @options[:max_pages])
+        return unless @more
 
         @next ||= begin
                     unless @page_cutoff
@@ -80,6 +78,8 @@ class Pagy
         @more = true          # not the last page
         @set.limit(nil).to_a  # replaced by the compound predicate
       end
+
+      prepend Deprecated::Keynav if defined?(Deprecated::Keynav)
     end
   end
 end

data/lib/pagy/classes/keyset/keyset.rb

@@ -4,9 +4,9 @@ require 'json'
 require_relative '../../modules/b64'
 
 class Pagy
-  # Implement wicked-fast keyset pagination for big data
+  # Fast keyset pagination for big data
   class Keyset < Pagy
-    # Autoload adapters: files are loaded only when const_get accesses them
+    # Autoload adapters only when const_get accesses them
     module Adapters
       path = Pathname.new(__dir__)
       autoload :ActiveRecord, path.join('adapters/active_record')
@@ -21,7 +21,7 @@ class Pagy
 
     class TypeError < ::TypeError; end
 
-    # Factory method: detects the set type, configures the subclass, and instantiates
+    # Factory method: detect the set type, configure the subclass, and instantiate.
     def self.new(set, **)
       # 1. Handle direct subclass usage (e.g. Pagy::Keyset::ActiveRecord.new)
       if /::(?:ActiveRecord|Sequel)$/.match?(name)
@@ -42,7 +42,7 @@ class Pagy
       const_get(adapter).tap { _1.mix_in_adapter(adapter) }.new(set, **)
     end
 
-    # Helper to lazy-include the adapter module
+    # Lazy-include the adapter module
     def self.mix_in_adapter(adapter)
       adapter_module = Adapters.const_get(adapter)
       include(adapter_module) unless self < adapter_module
@@ -61,7 +61,7 @@ class Pagy
       self.next
     end
 
-    # Return the array of records for the current page
+    # The array of records for the current page
     def records
       @records ||= begin
                      ensure_select
@@ -69,7 +69,7 @@ class Pagy
                    end
     end
 
-    # Return the next page (i.e., the cutoff of the current page)
+    # The next page (i.e., the cutoff of the current page)
     def next
       records
       return unless @more
@@ -135,13 +135,12 @@ class Pagy
       "#{hint} AND (#{query})"
     end
 
-    # Return the prefixed arguments from a cutoff
+    # The prefixed arguments from a cutoff
     def arguments_from(cutoff, prefix = nil)
       attributes = typecast(@keyset.keys.zip(cutoff).to_h)
       prefix ? attributes.transform_keys { |key| :"#{prefix}#{key}" } : attributes
     end
 
-    # Extract the cutoff from the last record (only called if @more)
     def extract_cutoff
       attributes = keyset_attributes_from(@records.last)
       @options[:pre_serialize]&.(attributes)

data/lib/pagy/classes/offset/countless.rb

@@ -2,13 +2,12 @@
 
 class Pagy
   class Offset
-    # Offset pagination without a count
+    # Offset pagination without any COUNT query
     class Countless < Offset
       def initialize(**)
         assign_options(**)
         assign_and_check(limit: 1, page: 1)
-        @page = upto_max_pages(@page)
-        @last = upto_max_pages(@options[:last]) unless @options[:headless]
+        @last = @options[:last] unless @options[:headless]
         assign_offset
       end
 
@@ -24,12 +23,6 @@ class Pagy
 
       def countless? = true
 
-      def upto_max_pages(value)
-        return value unless value && @options[:max_pages]
-
-        [value, @options[:max_pages]].min
-      end
-
       # Finalize the instance variables based on the fetched size
       def finalize(fetched_size)
         # empty records (trigger the right info message for known 0 count)
@@ -42,7 +35,7 @@ class Pagy
 
         past  = @last && @page < @last # current page is before the known last page
         more  = fetched_size > @limit  # more pages after this one
-        @last = upto_max_pages(more ? @page + 1 : @page) unless past && more
+        @last = (more ? @page + 1 : @page) unless past && more
         @in   = [fetched_size, @limit].min
         @from = @in.zero? ? 0 : @offset + 1
         @to   = @offset + @in
@@ -63,6 +56,8 @@ class Pagy
       def compose_page_param(page)
         EscapedValue.new("#{page || 1}+#{@last}")
       end
+
+      prepend Deprecated::Countless if defined?(Deprecated::Countless)
     end
   end
 end

data/lib/pagy/classes/offset/offset.rb

@@ -46,7 +46,6 @@ class Pagy
 
     def assign_last
       @last = [(@count.to_f / @limit).ceil, 1].max
-      @last = @options[:max_pages] if @options[:max_pages] && @last > @options[:max_pages]
     end
 
     def assign_offset
@@ -58,5 +57,7 @@ class Pagy
       @in = @from = @to = 0     # options relative to the actual page
       @previous = @last         # @previous relative to the actual page
     end
+
+    prepend Deprecated::Offset if defined?(Deprecated::Offset)
   end
 end

data/lib/pagy/classes/offset/search.rb

@@ -15,7 +15,7 @@ class Pagy
   end
 
   # Search classes do not use OFFSET for querying a DB;
-  # however, they use the same positional technique used by Offset
+  # however, they use the same positional technique used by Offset.
   class SearchBase < Offset
     DEFAULT = { search_method: :search }.freeze
 

data/lib/pagy/classes/request.rb

@@ -28,7 +28,7 @@ class Pagy
 
     def resolve_limit
       default   = @options[:limit] || DEFAULT[:limit]
-      max_limit = @options[:client_max_limit]
+      max_limit = @options[:max_limit]
       return default unless max_limit
 
       limit_key = @options[:limit_key] || DEFAULT[:limit_key]
@@ -38,8 +38,11 @@ class Pagy
 
     private
 
+    # Overriding support
     def get_params(request)
       request.GET.merge(request.POST).to_h.freeze
     end
+
+    prepend Deprecated::Request if defined?(Deprecated::Request)
   end
 end

data/lib/pagy/deprecated.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# This file relegates all the deprecation warnings and code.
+# Pagy already implements the next code and this file works as a compatibility layer
+# to avoid breaking changes in the current version, respecting the Semantic Version contract.
+class Pagy
+  module Deprecated
+    def self.client_max_limit(options)
+      if (max_limit = options.delete(:client_max_limit))
+        options[:max_limit] ||= max_limit
+        warn '[PAGY] the :client_max_limit option is deprecated: use :max_limit instead.'
+      end
+    end
+
+    module Pagy
+      def assign_options(**options)
+        if options.key?(:max_pages)
+          warn '[PAGY] the :max_pages option is deprecated: ' \
+               'use https://ddnexus.github.io/pagy/guides/how-to/#paginate-only-max-records instead.'
+        end
+        Deprecated.client_max_limit(options) # if used without Request#resolve_limit
+        super
+      end
+    end
+
+    ##### Enabled from the autoloaded class #####
+
+    module Request  # :client_max_limit option
+      def resolve_limit
+        Deprecated.client_max_limit(@options)
+        super
+      end
+    end
+
+    module Offset
+      def assign_last
+        super
+        @last = @options[:max_pages] if @options[:max_pages] && @last > @options[:max_pages]
+      end
+    end
+
+    module Countless
+      def initialize(**)
+        super
+        @page = upto_max_pages(@page)
+        @last = upto_max_pages(@last) unless @options[:headless]
+      end
+
+      def finalize(fetched_size)
+        super
+        @last = upto_max_pages(@last)
+      end
+
+      def upto_max_pages(value)
+        return value unless value && @options[:max_pages]
+
+        [value, @options[:max_pages]].min
+      end
+    end
+
+    module Keynav
+      def next
+        records
+        super unless @options[:max_pages] && @page >= @options[:max_pages]
+      end
+    end
+  end
+
+  prepend Deprecated::Pagy
+
+  # Reopen the module and add the deprecated methods
+  module Configurable
+    def options
+      OPTIONS.tap do
+        warn "[PAGY] 'Pagy.options' is deprecated: use 'Pagy::OPTIONS directly'"
+      end
+    end
+
+    def sync_javascript(...)
+      warn "[PAGY] 'Pagy.sync_javascript(...)' is deprecated: use 'Pagy.sync(:javascript, ...)' instead."
+      sync(:javascript, ...)
+    end
+  end
+end

data/lib/pagy/modules/abilities/configurable.rb

@@ -1,14 +1,8 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Add configuration methods
+  # Configuration methods
   module Configurable
-    # Deprecated: Sync the pagy javascript targets. Use sync(:javascripts, ...) instead.
-    def sync_javascript(...)
-      warn "[PAGY] 'Pagy.sync_javascript(...)' is deprecated: use 'Pagy.sync(:javascript, ...)' instead."
-      sync(:javascript, ...)
-    end
-
     # Sync the pagy resource targets.
     def sync(resource, destination, *targets)
       files    = ROOT.join("#{resource}s").glob("{#{targets.join(',')}}")

data/lib/pagy/modules/abilities/countable.rb

@@ -1,11 +1,10 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Provide the helpers to count a collection
+  # Count a collection
   module Countable
     module_function
 
-    # Get the collection count
     def get_count(collection, options)
       return collection.size if collection.instance_of?(Array)
       return collection.count unless defined?(::ActiveRecord) && collection.is_a?(::ActiveRecord::Relation)

data/lib/pagy/modules/abilities/linkable.rb

@@ -6,13 +6,13 @@ class Pagy
   # Support spaces in placeholder params
   class EscapedValue < String; end
 
-  # Provide the helpers to handle the url and anchor
+  # Handle the url and anchor
   module Linkable
     module QueryUtils
       module_function
 
-      # Extracted from Rack::Utils and reformatted for rubocop
-      # Allow unescaped Pagy::RawQueryValue
+      # Extracted from Rack::Utils and reformatted for rubocop.
+      # Allow unescaped Pagy::RawQueryValue.
       def build_nested_query(value, prefix = nil)
         case value
         when Array
@@ -38,7 +38,7 @@ class Pagy
 
     protected
 
-    # Overridable by classes with composite page param
+    # Overriding support for classes with composite page param
     def compose_page_param(page) = page
 
     # Return the URL for the page, relying on the Pagy::Request
@@ -53,7 +53,7 @@ class Pagy
                   end
 
       { opts[:page_key]  => compose_page_param(page),
-        opts[:limit_key] => opts[:client_max_limit] && opts[:limit] }.each do |k, v|
+        opts[:limit_key] => opts[:max_limit] && opts[:limit] }.each do |k, v|
         v ? container[k] = v : container.delete(k)
       end
 
@@ -63,6 +63,7 @@ class Pagy
       compose_url(opts[:absolute], opts[:path], params, fragment)
     end
 
+    # Overriding support
     def compose_url(absolute, path, params, fragment)
       query_string = QueryUtils.build_nested_query(params).sub(/\A(?=.)/, '?') # conditionally prepend '?'
       "#{@request.base_url if absolute}#{path || @request.path}#{query_string}#{fragment}"

data/lib/pagy/modules/abilities/rangeable.rb

@@ -1,9 +1,8 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Add method supporting range checking, range error and rescue
+  # Support range checking, error and rescue
   module Rangeable
-    # Check if in range
     def in_range?
       return @in_range if defined?(@in_range)
       return true if (@in_range = yield)

data/lib/pagy/modules/console.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Provide a ready to use pagy environment when included in irb/rails console
+  # Ready to use pagy environment when included in irb/rails console
   module Console
     class Collection < Array
       def initialize(arr = Array(1..1000))

data/lib/pagy/modules/i18n/i18n.rb

@@ -4,7 +4,7 @@ require 'yaml'
 require_relative 'p11n'
 
 class Pagy
-  # Pagy i18n implementation, compatible with the I18n gem, just a lot faster and lighter
+  # Faster and lighter Pagy i18n implementation, compatible with the I18n gem
   module I18n
     class KeyError < KeyError; end
 

data/lib/pagy/modules/searcher.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Relegate internal functions. Make overriding search classes easier.
   module Searcher
     module_function
 

data/lib/pagy/next.rb

@@ -0,0 +1,25 @@
+# See https://ddnexus.github.io/pagy/guides/pagy-next/
+# frozen_string_literal: true
+
+ENV['PAGY_NEXT'] = 'true'
+# :nocov:
+require_relative '../pagy' unless defined?(Pagy)  # avoid circular require (also from pagy itself)
+# :nocov:
+
+class Pagy
+  VERSION = "#{remove_const(:VERSION)}.next".freeze
+
+  class NextError < ArgumentError; end
+
+  module Discontinued
+    # Ensure a discontinued option won't pass unnoticed shadowing a bug
+    def assign_options(**options)
+      discontinued = options.keys & %i[max_pages client_max_limit]
+      return super if discontinued.empty?
+
+      raise NextError, "discontinued #{discontinued.map(&:inspect).join(', ')}: " \
+                       'check https://ddnexus.github.io/pagy/changelog/#deprecations for alternatives'
+    end
+  end
+  prepend Discontinued
+end

data/lib/pagy/tasks/sync.rb

@@ -5,6 +5,7 @@ require 'rake/tasklib'
 
 class Pagy
   class SyncTask < Rake::TaskLib
+    # Define a rake task for syncing a specific resource on demand
     def initialize(resource, destination, *targets)
       namespace :pagy do
         namespace :sync do

data/lib/pagy/toolbox/helpers/anchor_tags.rb

@@ -4,11 +4,9 @@ require_relative 'support/a_lambda' # inheritable
 
 class Pagy
   module NumericHelpers
-    # Return the enabled/disabled previous page anchor tag
     def previous_tag(...) = anchor_tag_for(:previous, ...)
   end
 
-  # Return the enabled/disabled next page anchor tag
   def next_tag(...) = anchor_tag_for(:next, ...)
 
   private

data/lib/pagy/toolbox/helpers/bootstrap/input_nav_js.rb

@@ -7,7 +7,6 @@ class Pagy
   module NumericHelpers
     private
 
-    # Javascript combo pagination for bootstrap: it returns a nav with a data-pagy attribute used by the pagy.js file
     def bootstrap_input_nav_js(classes: 'pagination', **)
       a_lambda = a_lambda(**)
 

data/lib/pagy/toolbox/helpers/bootstrap/previous_next_html.rb

@@ -4,7 +4,6 @@ class Pagy
   module NumericHelpers
     private
 
-    # Return the enabled/disabled previous/next page anchor tag, embedded in the li tag
     def bootstrap_html_for(which, a_lambda)
       if send(which)
         %(<li class="page-item #{which}">#{

data/lib/pagy/toolbox/helpers/bootstrap/series_nav.rb

@@ -7,7 +7,6 @@ class Pagy
   module NumericHelpers
     private
 
-    # Pagination for bootstrap: it returns the html with the series of links to the pages
     def bootstrap_series_nav(classes: 'pagination', **)
       a_lambda = a_lambda(**)
 

data/lib/pagy/toolbox/helpers/bootstrap/series_nav_js.rb

@@ -7,7 +7,6 @@ class Pagy
   module NumericHelpers
     private
 
-    # Javascript pagination for bootstrap: it returns a nav with a data-pagy attribute used by the pagy.js file
     def bootstrap_series_nav_js(classes: 'pagination', **)
       a_lambda = a_lambda(**)
 

data/lib/pagy/toolbox/helpers/bulma/input_nav_js.rb

@@ -7,7 +7,6 @@ class Pagy
   module NumericHelpers
     private
 
-    # Javascript combo pagination for bulma: it returns a nav with a data-pagy attribute used by the pagy.js file
     def bulma_input_nav_js(classes: 'pagination', **)
       a_lambda = a_lambda(**)
 

data/lib/pagy/toolbox/helpers/bulma/previous_next_html.rb

@@ -4,7 +4,6 @@ class Pagy
   module NumericHelpers
     private
 
-    # Return the enabled/disabled previous/next page anchor tag
     def bulma_html_for(which, a_lambda)
       %(<li>#{
         if send(which)

data/lib/pagy/toolbox/helpers/bulma/series_nav.rb

@@ -7,7 +7,6 @@ class Pagy
   module NumericHelpers
     private
 
-    # Pagination for bulma: it returns the html with the series of links to the pages
     def bulma_series_nav(classes: 'pagination', **)
       a_lambda = a_lambda(**)
 

data/lib/pagy/toolbox/helpers/bulma/series_nav_js.rb

@@ -7,7 +7,6 @@ class Pagy
   module NumericHelpers
     private
 
-    # Javascript pagination for bulma: it returns a nav with a data-pagy attribute used by the Pagy.nav javascript
     def bulma_series_nav_js(classes: 'pagination', **)
       a_lambda = a_lambda(**)
 

data/lib/pagy/toolbox/helpers/headers_hash.rb

@@ -2,7 +2,7 @@
 
 require_relative 'urls_hash'
 
-# Add pagination response headers
+# Handle pagination response headers
 class Pagy
   DEFAULT_HEADERS_MAP = { page:  'current-page',
                           limit: 'page-limit',

data/lib/pagy/toolbox/helpers/info_tag.rb

@@ -2,8 +2,8 @@
 
 class Pagy
   module NumericHelpers
-    # Instances with count return "Displaying items 41-60 of 324 in total" or "Displaying Products 41-60 of 324 in total"
-    # Instances with no count return only page info: "Page 3 of 100"
+    # Instances with count return "Displaying items 41-60 of 324 in total" or "Displaying Products 41-60 of 324 in total".
+    # Instances with no count return only page info: "Page 3 of 100".
     def info_tag(id: nil, item_name: nil)
       i18n_key  = if @count.nil?
                     'pagy.info_tag.no_count'

data/lib/pagy/toolbox/helpers/input_nav_js.rb

@@ -4,7 +4,6 @@ require_relative 'support/wrap_input_nav_js'
 
 class Pagy
   module NumericHelpers
-    # JavaScript input pagination: it returns a nav with a data-pagy attribute used by the pagy.js file
     def input_nav_js(style = nil, **)
       return send(:"#{style}_input_nav_js", **) if style && style.to_s != 'pagy'
 

data/lib/pagy/toolbox/helpers/limit_tag_js.rb

@@ -4,11 +4,10 @@ require_relative 'support/data_pagy_attribute'
 
 class Pagy
   module NumericHelpers
-    # Return the limit selector HTML. For example "Show [20] items per page"
-    def limit_tag_js(id: nil, item_name: nil, client_max_limit: @options[:client_max_limit], **)
-      raise OptionError.new(self, :client_max_limit, 'to be truthy', client_max_limit) unless client_max_limit
+    def limit_tag_js(id: nil, item_name: nil, max_limit: @options[:max_limit], **)
+      raise OptionError.new(self, :max_limit, 'to be truthy', max_limit) unless max_limit
 
-      limit_input = %(<input name="limit" type="number" min="1" max="#{client_max_limit}" value="#{
+      limit_input = %(<input name="limit" type="number" min="1" max="#{max_limit}" value="#{
                       @limit}" style="padding: 0; text-align: center; width: #{@limit.to_s.length + 1}rem;">#{A_TAG})
 
       url_token = compose_page_url(PAGE_TOKEN, limit: LIMIT_TOKEN)

data/lib/pagy/toolbox/helpers/loaders.rb

@@ -2,7 +2,7 @@
 
 class Pagy
   # The aliaser defines loader methods and aliases them.
-  # When a method is called for the first time, its loader will load the full implementation
+  # When a method is called for the first time, its loader will load the full implementation,
   # which will overwrite the alias and will be executed.
   # Subsequent calls will run the full implementation directly.
   aliaser = lambda do |receiver, paths|

data/lib/pagy/toolbox/helpers/page_url.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Return the page url for any page
   def page_url(page, **)
     target = case page
              when :first          then nil

data/lib/pagy/toolbox/helpers/series_nav.rb

@@ -4,7 +4,6 @@ require_relative 'support/wrap_series_nav'
 
 class Pagy
   module NumericHelpers
-    # Return the HTML with the series of links to the pages
     def series_nav(style = nil, **)
       return send(:"#{style}_series_nav", **) if style && style.to_s != 'pagy'
 

data/lib/pagy/toolbox/helpers/series_nav_js.rb

@@ -4,7 +4,6 @@ require_relative 'support/wrap_series_nav_js'
 
 class Pagy
   module NumericHelpers
-    # Return a nav with a data-pagy attribute used by the pagy.js file
     def series_nav_js(style = nil, **)
       return send(:"#{style}_series_nav_js", **) if style && style.to_s != 'pagy'