pagy 5.0.0 → 5.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c5f4f4ffd2a294e465f0a026d9795c9ae8e5efe58b968a97df08fa9163bab28
-  data.tar.gz: 8dc70a9adb26aa4da11f42f1903478d62b3aaff7a17e0bd57163c4b340ffd91e
+  metadata.gz: 4af6c795ba446552a412f0f45e76a267cf767d8f4dec3564a90096525bb298ea
+  data.tar.gz: 57a3f62877f0ed653ebe68f59963fb865e252e68c55e5c3a91794b9aa3b9584a
 SHA512:
-  metadata.gz: c3b6c77ae8ec22c135f6acc127884a4fe334e811b310ffa464bacae46d842a57a1d3c98faac019935c14900fe78aff2aeb0ebf72fef82822bea8dee9fc1943eb
-  data.tar.gz: 43b8b9aa866735df4ac4cca43b22f04aaa5c08ef9140c3d6b04b4ed0e132681e40f0ef224111dc788c0e558d3b8ac3d5e283d5a42ad24abc4c152a452b5ed5c5
+  metadata.gz: 0520f9933ea293895b8d26b0a78ea0af1a61054b5b89fce3a06c1f8f292d82357f6e105f76ab7bd4665f6ee9765bc69ce284428b8fe61b8f0a6b4768136c8e4a
+  data.tar.gz: '0903950d58220f510b5c2700b42f23f19c5cd267bc73eb5404d918863717b816836609256ef3a340534a9bc74e50260915b8b023b502c9dbe503bb443fab968f'

data/lib/config/pagy.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Pagy initializer file (5.0.0)
+# Pagy initializer file (5.1.2)
 # Customize only what you really need and notice that Pagy works also without any of the following lines.
 # Should you just cherry pick part of this file, please maintain the require-order of the extras
 
@@ -153,6 +153,11 @@
 # set to false only if you want to make :trim_extra an opt-in variable
 # Pagy::DEFAULT[:trim_extra] = false # default true
 
+# Standalone extra: Use pagy in non Rack environment/gem
+# See https://ddnexus.github.io/pagy/extras/standalone
+# require 'pagy/extras/standalone'
+# Pagy::DEFAULT[:url] = 'http://www.example.com/subdir'  # optional default
+
 
 # Rails
 

data/lib/javascripts/pagy.js

@@ -3,7 +3,7 @@
 // Container of the whole pagy stuff
 function Pagy(){}
 
-Pagy.version = '5.0.0'
+Pagy.version = '5.1.2'
 
 // Used by the waitForMe function
 Pagy.delay = 100

data/lib/pagy/backend.rb

@@ -15,16 +15,17 @@ class Pagy
     end
 
     # Sub-method called only by #pagy: here for easy customization of variables by overriding
+    # You may need to override the count call for non AR collections
     def pagy_get_vars(collection, vars)
       pagy_set_items_from_params(vars) if defined?(ItemsExtra)
-      vars[:count] ||= (c = collection.count(:all)).is_a?(Hash) ? c.size : c
+      vars[:count] ||= (count = collection.count(:all)).is_a?(Hash) ? count.size : count
       vars[:page]  ||= params[vars[:page_param] || DEFAULT[:page_param]]
       vars
     end
 
     # Sub-method called only by #pagy: here for easy customization of record-extraction by overriding
+    # You may need to override this method for collections without offset|limit
     def pagy_get_items(collection, pagy)
-      # This should work with ActiveRecord, Sequel, Mongoid...
       collection.offset(pagy.offset).limit(pagy.items)
     end
   end

data/lib/pagy/console.rb

@@ -5,8 +5,9 @@ require 'pagy'  # so you can require just the extra in the console
 require 'pagy/extras/standalone'
 
 class Pagy
-  # Provide ready to use pagy environment when included in irb/rails console
+  # Provide a ready to use pagy environment when included in irb/rails console
   module Console
+    # Include Backend, Frontend and set the default URL
     def self.included(main)
       main.include(Backend)
       main.include(Frontend)

data/lib/pagy/countless.rb

@@ -14,18 +14,23 @@ class Pagy
       @offset = (@items * (@page - 1)) + @outset
     end
 
-    # Finalize the instance variables based on the fetched items
-    def finalize(fetched)
-      raise OverflowError.new(self), "page #{@page} got no items" \
-            if fetched.zero? && @page > 1
+    # Finalize the instance variables based on the fetched size
+    def finalize(fetched_size)
+      raise OverflowError.new(self, :page, "to be < #{@page}") if fetched_size.zero? && @page > 1
 
-      @pages = @last = (fetched > @items ? @page + 1 : @page)
-      @in    = [fetched, @items].min
+      @pages = @last = (fetched_size > @items ? @page + 1 : @page)
+      @in    = [fetched_size, @items].min
       @from  = @in.zero? ? 0 : @offset - @outset + 1
       @to    = @offset - @outset + @in
       @prev  = (@page - 1 unless @page == 1)
       @next  = @page == @last ? (1 if @vars[:cycle]) : @page + 1
       self
     end
+
+    # Override the original series.
+    # Return nil if :countless_minimal is enabled
+    def series(_size = @vars[:size])
+      super unless @vars[:countless_minimal]
+    end
   end
 end

data/lib/pagy/exceptions.rb

@@ -3,23 +3,25 @@
 class Pagy
   # Generic variable error
   class VariableError < ArgumentError
-    attr_reader :pagy
+    attr_reader :pagy, :variable, :value
 
-    def initialize(pagy)
-      super
-      @pagy = pagy
-    end
-
-    def variable
-      message =~ /expected :(\w+)/
-      Regexp.last_match(1)&.to_sym
-    end
-
-    def value
-      pagy.vars[variable]
+    # Set the variables and prepare the message
+    def initialize(pagy, variable, description, value = nil)
+      @pagy     = pagy
+      @variable = variable
+      @value    = value
+      message   = +"expected :#{@variable} #{description}"
+      message  << "; got #{@value.inspect}" if value
+      super message
     end
   end
 
   # Specific overflow error
   class OverflowError < VariableError; end
+
+  # I18n configuration error
+  class I18nError < StandardError; end
+
+  # Generic internal error
+  class InternalError < StandardError; end
 end

data/lib/pagy/extras/bootstrap.rb

@@ -4,6 +4,8 @@
 require 'pagy/extras/shared'
 
 class Pagy
+  # Frontend modules are specially optimized for performance.
+  # The resulting code may not look very elegant, but produces the best benchmarks
   module BootstrapExtra
     # Pagination for bootstrap: it returns the html with the series of links to the pages
     def pagy_bootstrap_nav(pagy, pagy_id: nil, link_extra: '')
@@ -20,6 +22,7 @@ class Pagy
                   %(<li class="page-item active">#{link.call item}</li>)
                 when :gap
                   %(<li class="page-item gap disabled"><a href="#" class="page-link">#{pagy_t 'pagy.nav.gap'}</a></li>)
+                else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
       html << pagy_bootstrap_next_html(pagy, link)

data/lib/pagy/extras/bulma.rb

@@ -4,6 +4,8 @@
 require 'pagy/extras/shared'
 
 class Pagy
+  # Frontend modules are specially optimized for performance.
+  # The resulting code may not look very elegant, but produces the best benchmarks
   module BulmaExtra
     # Pagination for Bulma: it returns the html with the series of links to the pages
     def pagy_bulma_nav(pagy, pagy_id: nil, link_extra: '')
@@ -22,6 +24,7 @@ class Pagy
                                     %(class="pagination-link is-current" aria-label="page #{item}" aria-current="page")}</li>)
                 when :gap
                   %(<li><span class="pagination-ellipsis">#{pagy_t 'pagy.nav.gap'}</span></li>)
+                else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
       html << %(</ul></nav>)

data/lib/pagy/extras/countless.rb

@@ -23,16 +23,13 @@ class Pagy
     end
 
     # Sub-method called only by #pagy_countless: here for easy customization of record-extraction by overriding
+    # You may need to override this method for collections without offset|limit
     def pagy_countless_get_items(collection, pagy)
-      # This should work with ActiveRecord, Sequel, Mongoid...
       return collection.offset(pagy.offset).limit(pagy.items) if pagy.vars[:countless_minimal]
 
-      items      = collection.offset(pagy.offset).limit(pagy.items + 1).to_a
-      items_size = items.size
-      items.pop if items_size == pagy.items + 1
-      # finalize may adjust pagy.items, so must be used after checking the size
-      pagy.finalize(items_size)
-      items
+      fetched = collection.offset(pagy.offset).limit(pagy.items + 1).to_a # eager load items + 1
+      pagy.finalize(fetched.size)                                         # finalize the pagy object
+      fetched[0, pagy.items]                                              # ignore eventual extra item
     end
   end
   Backend.prepend CountlessExtra

data/lib/pagy/extras/elasticsearch_rails.rb

@@ -19,8 +19,8 @@ class Pagy
 
     module ElasticsearchRails
       # Return an array used to delay the call of #search
-      # after the pagination variables are merged to the options
-      # it also pushes to the same array an eventually called method
+      # after the pagination variables are merged to the options.
+      # It also pushes to the same array an optional method call.
       def pagy_elasticsearch_rails(query_or_payload, **options)
         [self, query_or_payload, options].tap do |args|
           args.define_singleton_method(:method_missing) { |*a| args += a }
@@ -57,7 +57,7 @@ class Pagy
         pagy = ::Pagy.new(vars)
         # with :last_page overflow we need to re-run the method in order to get the hits
         return pagy_elasticsearch_rails(pagy_search_args, vars.merge(page: pagy.page)) \
-              if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
+               if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
 
         [pagy, called.empty? ? response : response.send(*called)]
       end

data/lib/pagy/extras/foundation.rb

@@ -4,6 +4,8 @@
 require 'pagy/extras/shared'
 
 class Pagy
+  # Frontend modules are specially optimized for performance.
+  # The resulting code may not look very elegant, but produces the best benchmarks
   module FoundationExtra
     # Pagination for Foundation: it returns the html with the series of links to the pages
     def pagy_foundation_nav(pagy, pagy_id: nil, link_extra: '')
@@ -17,6 +19,7 @@ class Pagy
                 when Integer then %(<li>#{link.call item}</li>)                        # page link
                 when String  then %(<li class="current">#{item}</li>)                  # active page
                 when :gap    then %(<li class="ellipsis gap" aria-hidden="true"></li>) # page gap
+                else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
       html << pagy_foundation_next_html(pagy, link)

data/lib/pagy/extras/gearbox.rb

@@ -13,7 +13,7 @@ class Pagy
       return super if !@vars[:gearbox_extra] || @vars[:items_extra]
 
       gearbox_items = @vars[:gearbox_items]
-      raise VariableError.new(self), "expected :gearbox_items to be an Array of positives; got #{gearbox_items.inspect}" \
+      raise VariableError.new(self, :gearbox_items, 'to be an Array of positives', gearbox_items) \
             unless gearbox_items.is_a?(Array) && gearbox_items.all? { |num| num.positive? rescue false } # rubocop:disable Style/RescueModifier
 
       @items = gearbox_items[@page - 1] || gearbox_items.last

data/lib/pagy/extras/items.rb

@@ -14,9 +14,9 @@ class Pagy  # Default variables for this extra
 
       # Set the items variable considering the params and other pagy variables
       def pagy_set_items_from_params(vars)
-        return if vars[:items]
-        return unless vars.key?(:items_extra) ? vars[:items_extra] : DEFAULT[:items_extra]
-        return unless (items = params[vars[:items_param] || DEFAULT[:items_param]])
+        return if vars[:items]                                                             # :items explicitly set
+        return unless vars.key?(:items_extra) ? vars[:items_extra] : DEFAULT[:items_extra] # :items_extra is false
+        return unless (items = params[vars[:items_param] || DEFAULT[:items_param]])        # no items from request params
 
         vars[:items] = [items.to_i, vars.key?(:max_items) ? vars[:max_items] : DEFAULT[:max_items]].compact.min
       end

data/lib/pagy/extras/materialize.rb

@@ -4,6 +4,8 @@
 require 'pagy/extras/shared'
 
 class Pagy
+  # Frontend modules are specially optimized for performance.
+  # The resulting code may not look very elegant, but produces the best benchmarks
   module MaterializeExtra
     # Pagination for materialize: it returns the html with the series of links to the pages
     def pagy_materialize_nav(pagy, pagy_id: nil, link_extra: '')
@@ -17,6 +19,7 @@ class Pagy
                 when Integer then %(<li class="waves-effect">#{link.call item}</li>)                           # page link
                 when String  then %(<li class="active">#{link.call item}</li>)                                 # active page
                 when :gap    then %(<li class="gap disabled"><a href="#">#{pagy_t 'pagy.nav.gap'}</a></li>)    # page gap
+                else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
       html << pagy_materialize_next_html(pagy, link)

data/lib/pagy/extras/meilisearch.rb

@@ -39,13 +39,13 @@ class Pagy
         pagy                 = ::Pagy.new(vars)
         # with :last_page overflow we need to re-run the method in order to get the hits
         return pagy_meilisearch(pagy_search_args, vars.merge(page: pagy.page)) \
-          if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
+               if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
 
         [pagy, results]
       end
 
-      # Sub-method called only by #pagy_meilisearch: here for easy customization of variables by overriding
-      # the _collection argument is not available when the method is called
+      # Sub-method called only by #pagy_meilisearch: here for easy customization of variables by overriding.
+      # The _collection argument is not available when the method is called.
       def pagy_meilisearch_get_vars(_collection, vars)
         pagy_set_items_from_params(vars) if defined?(ItemsExtra)
         vars[:items] ||= DEFAULT[:items]

data/lib/pagy/extras/metadata.rb

@@ -4,44 +4,20 @@
 require 'pagy/url_helpers'
 
 class Pagy
+  DEFAULT[:metadata] = %i[ scaffold_url first_url prev_url page_url next_url last_url
+                           count page items vars pages last in from to prev next series ]
+
   # Add a specialized backend method for pagination metadata
   module MetadataExtra
     private
 
-    # Store the array of all the internal variable names usable as METADATA
-    METADATA = %i[ scaffold_url
-                   first_url
-                   prev_url
-                   page_url
-                   next_url
-                   last_url
-                   count page
-                   items
-                   vars
-                   pages
-                   last
-                   in
-                   from
-                   to
-                   prev
-                   next
-                   series ].tap { |m| m << :sequels if DEFAULT.key?(:steps) }.freeze
-
-    # Set the default metadata variable
-    Pagy::DEFAULT[:metadata] = METADATA.dup
-
     include UrlHelpers
 
     # Return the metadata hash
     def pagy_metadata(pagy, absolute: nil)
-      names   = pagy.vars[:metadata]
-      unknown = names - METADATA
-      raise VariableError.new(pagy), "expected :metadata to be in #{DEFAULT[:metadata].inspect}, got #{unknown.inspect} unknown" \
-            unless unknown.empty?
-
       scaffold_url = pagy_url_for(pagy, PAGE_PLACEHOLDER, absolute: absolute)
       {}.tap do |metadata|
-        names.each do |key|
+        pagy.vars[:metadata].each do |key|
           metadata[key] = case key
                           when :scaffold_url then scaffold_url
                           when :first_url    then scaffold_url.sub(PAGE_PLACEHOLDER, 1.to_s)
@@ -51,6 +27,8 @@ class Pagy
                           when :last_url     then scaffold_url.sub(PAGE_PLACEHOLDER, pagy.last.to_s)
                           else pagy.send(key)
                           end
+        rescue NoMethodError
+          raise VariableError.new(pagy, :metadata, 'to contain known keys', key)
         end
       end
     end

data/lib/pagy/extras/navs.rb

@@ -4,6 +4,8 @@
 require 'pagy/extras/shared'
 
 class Pagy
+  # Frontend modules are specially optimized for performance.
+  # The resulting code may not look very elegant, but produces the best benchmarks
   module NavsExtra
     # Javascript pagination: it returns a nav and a JSON tag used by the Pagy.nav javascript
     def pagy_nav_js(pagy, pagy_id: nil, link_extra: '', steps: nil)

data/lib/pagy/extras/overflow.rb

@@ -31,11 +31,11 @@ class Pagy
           @prev = @last                             # prev relative to the actual page
           extend Series                             # special series for :empty_page
         else
-          raise VariableError.new(self), \
-                "expected :overflow to be in [:last_page, :empty_page, :exception]; got #{@vars[:overflow].inspect}"
+          raise VariableError.new(self, :overflow, 'to be in [:last_page, :empty_page, :exception]', @vars[:overflow])
         end
       end
 
+      # Special series for empty page
       module Series
         def series(size = @vars[:size])
           @page = @last                             # series for last page
@@ -63,8 +63,7 @@ class Pagy
           @vars[:size] = []                     # no page in the series
           self
         else
-          raise VariableError.new(self), \
-                "expected :overflow to be in [:empty_page, :exception]; got #{@vars[:overflow].inspect}"
+          raise VariableError.new(self, :overflow, 'to be in [:empty_page, :exception]', @vars[:overflow])
         end
       end
     end

data/lib/pagy/extras/searchkick.rb

@@ -7,8 +7,8 @@ class Pagy
   module SearchkickExtra
     module Searchkick
       # Return an array used to delay the call of #search
-      # after the pagination variables are merged to the options
-      # it also pushes to the same array an eventually called method
+      # after the pagination variables are merged to the options.
+      # It also pushes to the same array an optional method call.
       def pagy_searchkick(term = '*', **options, &block)
         [self, term, options, block].tap do |args|
           args.define_singleton_method(:method_missing) { |*a| args += a }
@@ -44,7 +44,7 @@ class Pagy
         pagy = ::Pagy.new(vars)
         # with :last_page overflow we need to re-run the method in order to get the hits
         return pagy_searchkick(pagy_search_args, vars.merge(page: pagy.page)) \
-              if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
+               if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
 
         [pagy, called.empty? ? results : results.send(*called)]
       end

data/lib/pagy/extras/semantic.rb

@@ -4,6 +4,8 @@
 require 'pagy/extras/shared'
 
 class Pagy
+  # Frontend modules are specially optimized for performance.
+  # The resulting code may not look very elegant, but produces the best benchmarks
   module SemanticExtra
     # Pagination for semantic: it returns the html with the series of links to the pages
     def pagy_semantic_nav(pagy, pagy_id: nil, link_extra: '')
@@ -17,6 +19,7 @@ class Pagy
                 when Integer then link.call item                                                 # page link
                 when String  then %(<a class="item active">#{item}</a>)                          # current page
                 when :gap    then %(<div class="disabled item">#{pagy_t 'pagy.nav.gap'}</div>)   # page gap
+                else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
       html << pagy_semantic_next_html(pagy, link)

data/lib/pagy/extras/shared.rb

@@ -19,8 +19,7 @@ class Pagy
       # Notice: if :steps is false it will use the single {0 => @vars[:size]} size
       def sequels(steps = nil)
         steps ||= @vars[:steps] || { 0 => @vars[:size] }
-        raise VariableError.new(self), "expected :steps to define the 0 width; got #{steps.inspect}" \
-              unless steps.key?(0)
+        raise VariableError.new(self, :steps, 'to define the 0 width', steps) unless steps.key?(0)
 
         {}.tap do |sequels|
           steps.each { |width, size| sequels[width.to_s] = series(size) }
@@ -31,14 +30,14 @@ class Pagy
     # Additions for the Frontend
     module Frontend
       if defined?(Oj)
-        # it returns a script tag with the JSON-serialized args generated with the faster oj gem
+        # Return a script tag with the JSON-serialized args generated with the faster oj gem
         def pagy_json_attr(pagy, *args)
           args << pagy.vars[:page_param] if pagy.vars[:trim_extra]
           %(data-pagy-json="#{Oj.dump(args, mode: :strict).gsub('"', '&quot;')}")
         end
       else
         require 'json'
-        # it returns a script tag with the JSON-serialized args generated with the slower to_json
+        # Return a script tag with the JSON-serialized args generated with the slower to_json
         def pagy_json_attr(pagy, *args)
           args << pagy.vars[:page_param] if pagy.vars[:trim_extra]
           %(data-pagy-json="#{args.to_json.gsub('"', '&quot;')}")

data/lib/pagy/extras/standalone.rb

@@ -3,6 +3,8 @@
 
 require 'uri'
 class Pagy
+  # Use pagy without any request object, nor Rack environment/gem, nor any defined params method,
+  # even in the irb/rails console without any app or config.
   module StandaloneExtra
     # Extracted from Rack::Utils and reformatted for rubocop
     module QueryUtils
@@ -30,21 +32,22 @@ class Pagy
       end
     end
 
-    # Without any :url var it works exactly as the regular #pagy_url_for;
-    # with a defined :url variable it does not use rack/request
+    # Return the URL for the page. If there is no pagy.vars[:url]
+    # it works exactly as the regular #pagy_url_for, relying on the params method and Rack.
+    # If there is a defined pagy.vars[:url] variable it does not need the params method nor Rack.
     def pagy_url_for(pagy, page, absolute: nil)
-      p_vars = pagy.vars
-      return super unless (url = p_vars[:url])
-
-      params                            = p_vars[:params]
-      params[p_vars[:page_param].to_s]  = page
-      params[p_vars[:items_param].to_s] = p_vars[:items] if defined?(ItemsExtra)
-      # no Rack required in standalone mode
-      query_string = "?#{QueryUtils.build_nested_query(pagy_massage_params(params))}" unless params.empty?
-      "#{url}#{query_string}#{p_vars[:fragment]}"
+      vars = pagy.vars
+      return super unless (url = vars[:url])
+
+      params                     = vars[:params].clone  # safe when it gets reused
+      params[vars[:page_param]]  = page
+      params[vars[:items_param]] = vars[:items] if vars[:items_extra]
+
+      query_string = "?#{QueryUtils.build_nested_query(pagy_massage_params(params))}"
+      "#{url}#{query_string}#{vars[:fragment]}"
     end
   end
-  # In ruby 3+ we could just use `UrlHelpers.prepend StandaloneExtra` instead of using the next 2 lines
+  # In ruby 3+ `UrlHelpers.prepend StandaloneExtra` would be enough instead of using the next 2 lines
   Frontend.prepend StandaloneExtra
   Backend.prepend StandaloneExtra
 

data/lib/pagy/extras/support.rb

@@ -3,14 +3,17 @@
 
 class Pagy
   module SupportExtra
+    # Return the previous page URL string or nil
     def pagy_prev_url(pagy)
       pagy_url_for(pagy, pagy.prev) if pagy.prev
     end
 
+    # Return the next page URL string or nil
     def pagy_next_url(pagy)
       pagy_url_for(pagy, pagy.next) if pagy.next
     end
 
+    # Return the HTML string for the previous page link
     def pagy_prev_link(pagy, text: pagy_t('pagy.nav.prev'), link_extra: '')
       if pagy.prev
         %(<span class="page prev"><a href="#{
@@ -23,6 +26,7 @@ class Pagy
       end
     end
 
+    # Return the HTML string for the next page link
     def pagy_next_link(pagy, text: pagy_t('pagy.nav.next'), link_extra: '')
       if pagy.next
         %(<span class="page next"><a href="#{
@@ -35,10 +39,12 @@ class Pagy
       end
     end
 
+    # Return the HTML link tag for the previous page or nil
     def pagy_prev_link_tag(pagy)
       %(<link href="#{pagy_url_for(pagy, pagy.prev)}" rel="prev"/>) if pagy.prev
     end
 
+    # Return the HTML link tag for the next page or nil
     def pagy_next_link_tag(pagy)
       %(<link href="#{pagy_url_for(pagy, pagy.next)}" rel="next"/>) if pagy.next
     end

data/lib/pagy/extras/trim.rb

@@ -5,7 +5,8 @@ class Pagy
   DEFAULT[:trim_extra] = true   # extra enabled by default
 
   module TrimExtra
-    # Override the original using the pagy_trim method
+    # Override the original pagy_link_proc.
+    # Call the pagy_trim method if the trim_extra is enabled.
     def pagy_link_proc(pagy, link_extra: '')
       link_proc = super(pagy, link_extra: link_extra)
       return link_proc unless pagy.vars[:trim_extra]

data/lib/pagy/extras/uikit.rb

@@ -4,6 +4,8 @@
 require 'pagy/extras/shared'
 
 class Pagy
+  # Frontend modules are specially optimized for performance.
+  # The resulting code may not look very elegant, but produces the best benchmarks
   module UikitExtra
     # Pagination for uikit: it returns the html with the series of links to the pages
     def pagy_uikit_nav(pagy, pagy_id: nil, link_extra: '')
@@ -16,6 +18,7 @@ class Pagy
                 when Integer then %(<li>#{link.call item}</li>)
                 when String  then %(<li class="uk-active"><span>#{item}</span></li>)
                 when :gap    then %(<li class="uk-disabled"><span>#{pagy_t 'pagy.nav.gap'}</span></li>)
+                else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
       html << pagy_uikit_next_html(pagy, link)

data/lib/pagy/frontend.rb

@@ -8,8 +8,8 @@ class Pagy
   # Used for search and replace, hardcoded also in the pagy.js file
   PAGE_PLACEHOLDER = '__pagy_page__'
 
-  # All the code here has been optimized for performance: it may not look very pretty
-  # (as most code dealing with many long strings), but its performance makes it very sexy! ;)
+  # Frontend modules are specially optimized for performance.
+  # The resulting code may not look very elegant, but produces the best benchmarks
   module Frontend
     include UrlHelpers
 
@@ -31,6 +31,7 @@ class Pagy
                 when Integer then %(<span class="page">#{link.call item}</span> )               # page link
                 when String  then %(<span class="page active">#{item}</span> )                  # current page
                 when :gap    then %(<span class="page gap">#{pagy_t('pagy.nav.gap')}</span> )   # page gap
+                else raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
                 end
       end
       html << if p_next

data/lib/pagy/i18n.rb

@@ -10,7 +10,7 @@ class Pagy
 
     # Pluralization rules
     module P11n
-      # utility variables
+      # Utility variables
       from0to1   = [0, 1].freeze
       from2to4   = [2, 3, 4].freeze
       from5to9   = [5, 6, 7, 8, 9].freeze
@@ -130,7 +130,7 @@ class Pagy
         locale[:filepath]  ||= Pagy.root.join('locales', "#{locale[:locale]}.yml")
         locale[:pluralize] ||= P11n::LOCALE[locale[:locale]]
         dictionary = YAML.safe_load(File.read(locale[:filepath], encoding: 'UTF-8'))
-        raise VariableError, %(expected :locale "#{locale[:locale]}" not found in :filepath "#{locale[:filepath].inspect}") \
+        raise I18nError, %(expected :locale "#{locale[:locale]}" not found in :filepath "#{locale[:filepath].inspect}") \
               unless dictionary.key?(locale[:locale])
 
         DATA[locale[:locale]] = [flatten(dictionary[locale[:locale]]), locale[:pluralize]]

data/lib/pagy/url_helpers.rb

@@ -3,15 +3,17 @@
 class Pagy
   # Provide the helpers to handle the url in frontend and backend
   module UrlHelpers
-    # This works with all Rack-based frameworks (Sinatra, Padrino, Rails, ...)
+    # Return the URL for the page, relying on the params method and Rack by default.
+    # It supports all Rack-based frameworks (Sinatra, Padrino, Rails, ...).
+    # For non-rack environments you can use the standalone extra
     def pagy_url_for(pagy, page, absolute: nil)
-      p_vars                            = pagy.vars
-      params                            = request.GET.merge(p_vars[:params])
-      params[p_vars[:page_param].to_s]  = page
-      params[p_vars[:items_param].to_s] = p_vars[:items] if defined?(ItemsExtra)
-      # we rely on Rack by default: use the standalone extra in non rack environments
-      query_string = "?#{Rack::Utils.build_nested_query(pagy_massage_params(params))}" unless params.empty?
-      "#{request.base_url if absolute}#{request.path}#{query_string}#{p_vars[:fragment]}"
+      vars                            = pagy.vars
+      params                          = request.params.merge(vars[:params].transform_keys(&:to_s))
+      params[vars[:page_param].to_s]  = page
+      params[vars[:items_param].to_s] = vars[:items] if vars[:items_extra]
+
+      query_string = "?#{Rack::Utils.build_nested_query(pagy_massage_params(params))}"
+      "#{request.base_url if absolute}#{request.path}#{query_string}#{vars[:fragment]}"
     end
 
     # Sub-method called only by #pagy_url_for: here for easy customization of params by overriding

data/lib/pagy.rb

@@ -5,7 +5,7 @@ require 'pathname'
 
 # Core class
 class Pagy
-  VERSION = '5.0.0'
+  VERSION = '5.1.2'
 
   # Root pathname to get the path of Pagy files like templates or dictionaries
   def self.root
@@ -32,8 +32,7 @@ class Pagy
     setup_vars(count: 0, page: 1, outset: 0)
     setup_items_var
     setup_pages_var
-    raise OverflowError.new(self), "expected :page in 1..#{@last}; got #{@page.inspect}" \
-          if @page > @last
+    raise OverflowError.new(self, :page, "in 1..#{@last}", @page) if @page > @last
 
     @offset = (@items * (@page - 1)) + @outset
     @from   = [@offset - @outset + 1, @count].min
@@ -46,7 +45,7 @@ class Pagy
   # Return the array of page numbers and :gap items e.g. [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
   def series(size = @vars[:size])
     return [] if size.empty?
-    raise VariableError.new(self), "expected 4 items >= 0 in :size; got #{size.inspect}" \
+    raise VariableError.new(self, :size, 'to contain 4 items >= 0', size) \
           unless size.size == 4 && size.all? { |num| !num.negative? rescue false } # rubocop:disable Style/RescueModifier
 
     # This algorithm is up to ~5x faster and ~2.3x lighter than the previous one (pagy < 4.3)
@@ -81,7 +80,7 @@ class Pagy
   # Setup and validates the passed vars: var must be present and value.to_i must be >= to min
   def setup_vars(name_min)
     name_min.each do |name, min|
-      raise VariableError.new(self), "expected :#{name} >= #{min}; got #{@vars[name].inspect}" \
+      raise VariableError.new(self, name, ">= #{min}", @vars[name]) \
             unless @vars[name] && instance_variable_set(:"@#{name}", @vars[name].to_i) >= min
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pagy
 version: !ruby/object:Gem::Version
-  version: 5.0.0
+  version: 5.1.2
 platform: ruby
 authors:
 - Domizio Demichelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-16 00:00:00.000000000 Z
+date: 2021-10-25 00:00:00.000000000 Z
 dependencies: []
 description: Agnostic pagination in plain ruby. It does it all. Better.
 email: