pagy 5.0.1 → 5.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a1345a70a6c730b386f155905f1f64821d0843704a378906cec76a27a68f77bc
-  data.tar.gz: b067a51f4178b84cf164374382b41e061e4d0e257819961abb2ef8d3e516c83d
+  metadata.gz: 46116524913f885ab10fb48fdac0c9b6691654e23abb04f138586791aaca7a3b
+  data.tar.gz: 911ca803f1f0764484c0440898d384c768c0ed94da1eeac7dd9317a66750b548
 SHA512:
-  metadata.gz: 8aa6a995fff4c56eade45efb978ad63beb36f2ee10152dbf89365cf18d66911f89a7f84f36b35ce94b4228a286f18b6343a6c30c80434bd9ad6a12c177b47b3e
-  data.tar.gz: 4a9288306aff02bfc789a3198f38c02ed6b7d038d2caddf1eba1d3b4102e4f1f61c111eefd60c126c6a4f5c2e3b88dd745802732324d506bed8bbd118361027f
+  metadata.gz: e2a7dcaf8febf7412f73bb54b2bba3189670faed1e58400ab68e8e0fe1c7de305cbe66be9a848762d2bad31bf8de082c6208ede39ff04027c6b71c283e356220
+  data.tar.gz: 43ee98762c7e8b1e777dd52d9c550f0b351691f2dad440dc65daeb0328fe1d0f2868830f4b34e75d2b45b10e0530140801bd3e65eb2938cc7ca54a94d65207c4

data/lib/config/pagy.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Pagy initializer file (5.0.1)
+# Pagy initializer file (5.1.0)
 # 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.1'
+Pagy.version = '5.1.0'
 
 // 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,12 +14,12 @@ 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, "to be < #{@page}") 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)
@@ -27,6 +27,8 @@ class Pagy
       self
     end
 
+    # Override the original series.
+    # Return nil if :countless_minimal is enabled
     def series(_size = @vars[:size])
       super unless @vars[:countless_minimal]
     end

data/lib/pagy/exceptions.rb

@@ -5,6 +5,7 @@ class Pagy
   class VariableError < ArgumentError
     attr_reader :pagy, :variable, :value
 
+    # Set the variables and prepare the message
     def initialize(pagy, variable, description, value = nil)
       @pagy     = pagy
       @variable = variable

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: '')

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: '')

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: '')

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: '')

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/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

@@ -35,6 +35,7 @@ class Pagy
         end
       end
 
+      # Special series for empty page
       module Series
         def series(size = @vars[:size])
           @page = @last                             # series for last page

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: '')

data/lib/pagy/extras/shared.rb

@@ -30,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

@@ -30,21 +30,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])
+      vars = pagy.vars
+      return super unless (url = vars[:url])
+
+      params                     = vars[:params]
+      params[vars[:page_param]]  = page
+      params[vars[:items_param]] = vars[:items] if vars[:items_extra]
 
-      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))}"
-      "#{url}#{query_string}#{p_vars[:fragment]}"
+      "#{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: '')

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
 

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

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
+      vars                       = pagy.vars
+      params                     = self.params.merge(vars[:params])
+      params[vars[:page_param]]  = page
+      params[vars[:items_param]] = 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}#{p_vars[:fragment]}"
+      "#{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.1'
+  VERSION = '5.1.0'
 
   # Root pathname to get the path of Pagy files like templates or dictionaries
   def self.root

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pagy
 version: !ruby/object:Gem::Version
-  version: 5.0.1
+  version: 5.1.0
 platform: ruby
 authors:
 - Domizio Demichelis
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2021-10-18 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: