pagy 8.0.0 → 9.0.0

data/lib/pagy/extras/searchkick.rb

@@ -23,11 +23,11 @@ class Pagy # :nodoc:
     # Additions for the Pagy class
     module PagyExtension
       # Create a Pagy object from a Searchkick::Results object
-      def new_from_searchkick(results, vars = {})
-        vars[:items] = results.options[:per_page]
+      def new_from_searchkick(results, **vars)
+        vars[:limit] = results.options[:per_page]
         vars[:page]  = results.options[:page]
         vars[:count] = results.total_count
-        new(vars)
+        new(**vars)
       end
     end
     Pagy.extend PagyExtension
@@ -37,17 +37,17 @@ class Pagy # :nodoc:
       private
 
       # Return Pagy object and results
-      def pagy_searchkick(pagy_search_args, vars = {})
+      def pagy_searchkick(pagy_search_args, **vars)
         model, term, options, block, *called = pagy_search_args
         vars               = pagy_searchkick_get_vars(nil, vars)
-        options[:per_page] = vars[:items]
+        options[:per_page] = vars[:limit]
         options[:page]     = vars[:page]
         results            = model.send(DEFAULT[:searchkick_search], term, **options, &block)
         vars[:count]       = results.total_count
 
-        pagy = ::Pagy.new(vars)
+        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)) \
+        return pagy_searchkick(pagy_search_args, **vars, page: pagy.page) \
                if defined?(::Pagy::OverflowExtra) && pagy.overflow? && pagy.vars[:overflow] == :last_page
 
         [pagy, called.empty? ? results : results.send(*called)]
@@ -56,10 +56,10 @@ class Pagy # :nodoc:
       # Sub-method called only by #pagy_searchkick: here for easy customization of variables by overriding
       # the _collection argument is not available when the method is called
       def pagy_searchkick_get_vars(_collection, vars)
-        pagy_set_items_from_params(vars) if defined?(ItemsExtra)
-        vars[:items] ||= DEFAULT[:items]
-        vars[:page]  ||= pagy_get_page(vars)
-        vars
+        vars.tap do |v|
+          v[:page]  ||= pagy_get_page(v)
+          v[:limit] ||= pagy_get_limit(v) || DEFAULT[:limit]
+        end
       end
     end
     Backend.prepend BackendAddOn

data/lib/pagy/extras/size.rb

@@ -0,0 +1,40 @@
+# See the Pagy documentation: https://ddnexus.github.io/pagy/docs/extras/size
+# frozen_string_literal: true
+
+class Pagy # :nodoc:
+  # Implement the legacy bar using the array size.
+  # Unless you have very specific requirements, use the faster and better looking default bar.
+  module SizeExtra
+    # Implements the old series algorithm
+    def series(size: @vars[:size], **_)
+      return super unless size.is_a?(Array)
+      return [] if size == []
+      raise VariableError.new(self, :size, 'to be an Array of 4 Integers or []', size) \
+            unless size.is_a?(Array) && size.size == 4 && size.all? { |num| !num.negative? rescue false } # rubocop:disable Style/RescueModifier
+
+      [].tap do |series|
+        # This algorithm is up to ~5x faster and ~2.3x lighter than the previous one (pagy < 4.3)
+        # However the behavior of the legacy nav bar was taken straight from WillPaginate and Kaminari:
+        # it's ill-concieved and complicates the experience of devs and users.
+        left_gap_start  = 1 + size[0]
+        left_gap_end    = @page - size[1] - 1
+        right_gap_start = @page + size[2] + 1
+        right_gap_end   = @last - size[3]
+        left_gap_end    = right_gap_end  if left_gap_end   > right_gap_end
+        right_gap_start = left_gap_start if left_gap_start > right_gap_start
+        start           = 1
+        if (left_gap_end - left_gap_start).positive?
+          series.push(*start...left_gap_start, :gap)
+          start = left_gap_end + 1
+        end
+        if (right_gap_end - right_gap_start).positive?
+          series.push(*start...right_gap_start, :gap)
+          start = right_gap_end + 1
+        end
+        series.push(*start..@last)
+        series[series.index(@page)] = @page.to_s
+      end
+    end
+  end
+  prepend SizeExtra
+end

data/lib/pagy/extras/standalone.rb

@@ -12,10 +12,6 @@ class Pagy # :nodoc:
     module QueryUtils
       module_function
 
-      def escape(str)
-        URI.encode_www_form_component(str)
-      end
-
       def build_nested_query(value, prefix = nil)
         case value
         when Array
@@ -32,21 +28,25 @@ class Pagy # :nodoc:
           "#{escape(prefix)}=#{escape(value)}"
         end
       end
+
+      def escape(str)
+        URI.encode_www_form_component(str)
+      end
     end
     # :nocov:
 
     # 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: false, **_)
+    def pagy_url_for(pagy, page, fragment: nil, **_)
       return super unless pagy.vars[:url]
 
       vars         = pagy.vars
-      params       = pagy.params.is_a?(Hash) ? pagy.params.clone : {}  # safe when it gets reused
+      params       = vars[:params].is_a?(Hash) ? vars[:params].clone : {}  # safe when it gets reused
       pagy_set_query_params(page, vars, params)
-      params       = pagy.params.call(params) if pagy.params.is_a?(Proc)
+      params       = vars[:params].(params) if vars[:params].is_a?(Proc)
       query_string = "?#{QueryUtils.build_nested_query(params)}"
-      "#{vars[:url]}#{query_string}#{vars[:fragment]}"
+      "#{vars[:url]}#{query_string}#{fragment}"
     end
   end
   UrlHelpers.prepend StandaloneExtra

data/lib/pagy/extras/trim.rb

@@ -6,10 +6,10 @@ class Pagy # :nodoc:
 
   # Remove the page=1 param from the first page link
   module TrimExtra
-    # Override the original pagy_a_proc.
+    # Override the original pagy_anchor.
     # Call the pagy_trim method for page 1 if the trim_extra is enabled
-    def pagy_anchor(pagy)
-      a_proc = super(pagy)
+    def pagy_anchor(pagy, **_)
+      a_proc = super
       return a_proc unless pagy.vars[:trim_extra]
 
       lambda do |page, text = pagy.label_for(page), **opts|

data/lib/pagy/frontend.rb

@@ -1,8 +1,8 @@
 # See Pagy::Frontend API documentation: https://ddnexus.github.io/pagy/docs/api/frontend
 # frozen_string_literal: true
 
-require 'pagy/url_helpers'
-require 'pagy/i18n'
+require_relative 'i18n'
+require_relative 'url_helpers'
 
 class Pagy
   # Used for search and replace, hardcoded also in the pagy.js file
@@ -14,13 +14,44 @@ class Pagy
   module Frontend
     include UrlHelpers
 
+    # Return a performance optimized lambda to generate the HTML anchor element (a tag)
+    # Benchmarked on a 20 link nav: it is ~22x faster and uses ~18x less memory than rails' link_to
+    def pagy_anchor(pagy, anchor_string: nil, **vars)
+      anchor_string &&= %( #{anchor_string})
+      left, right = %(<a#{anchor_string} href="#{pagy_url_for(pagy, PAGE_TOKEN, **vars)}").split(PAGE_TOKEN, 2)
+      # lambda used by all the helpers
+      lambda do |page, text = pagy.label_for(page), classes: nil, aria_label: nil|
+        classes    = %( class="#{classes}") if classes
+        aria_label = %( aria-label="#{aria_label}") if aria_label
+        %(#{left}#{page}#{right}#{classes}#{aria_label}>#{text}</a>)
+      end
+    end
+
+    # Return examples: "Displaying items 41-60 of 324 in total" or "Displaying Products 41-60 of 324 in total"
+    def pagy_info(pagy, id: nil, item_name: nil)
+      id      = %( id="#{id}") if id
+      p_count = pagy.count
+      key     = if p_count.zero?
+                  'pagy.info.no_items'
+                elsif pagy.pages == 1
+                  'pagy.info.single_page'
+                else
+                  'pagy.info.multiple_pages'
+                end
+
+      %(<span#{id} class="pagy info">#{
+          pagy_t key, item_name: item_name || pagy_t('pagy.item_name', count: p_count),
+                      count: p_count, from: pagy.from, to: pagy.to
+        }</span>)
+    end
+
     # Generic pagination: it returns the html with the series of links to the pages
-    def pagy_nav(pagy, id: nil, aria_label: nil, **vars)
+    def pagy_nav(pagy, id: nil, aria_label: nil, anchor_string: nil, **vars)
       id = %( id="#{id}") if id
-      a  = pagy_anchor(pagy)
+      a  = pagy_anchor(pagy, anchor_string:)
 
       html = %(<nav#{id} class="pagy nav" #{nav_aria_label(pagy, aria_label:)}>#{
-                prev_a(pagy, a)})
+                 prev_a(pagy, a)})
       pagy.series(**vars).each do |item| # series example: [1, :gap, 7, 8, "9", 10, 11, :gap, 36]
         html << case item
                 when Integer
@@ -36,39 +67,10 @@ class Pagy
       html << %(#{next_a(pagy, a)}</nav>)
     end
 
-    # Return examples: "Displaying items 41-60 of 324 in total" or "Displaying Products 41-60 of 324 in total"
-    def pagy_info(pagy, id: nil, item_name: nil)
-      id      = %( id="#{id}") if id
-      p_count = pagy.count
-      key     = if    p_count.zero?   then 'pagy.info.no_items'
-                elsif pagy.pages == 1 then 'pagy.info.single_page'
-                else                       'pagy.info.multiple_pages' # rubocop:disable Lint/ElseLayout
-                end
-
-      %(<span#{id} class="pagy info">#{
-          pagy_t key, item_name: item_name || pagy_t('pagy.item_name', count: p_count),
-                      count: p_count, from: pagy.from, to: pagy.to
-        }</span>)
-    end
-
-    # Return a performance optimized lambda to generate the HtML anchor element (a tag)
-    # Benchmarked on a 20 link nav: it is ~22x faster and uses ~18x less memory than rails' link_to
-    def pagy_anchor(pagy)
-      a_string    = pagy.vars[:anchor_string]
-      a_string    = %( #{a_string}) if a_string
-      left, right = %(<a#{a_string} href="#{pagy_url_for(pagy, PAGE_TOKEN)}").split(PAGE_TOKEN, 2)
-      # lambda used by all the helpers
-      lambda do |page, text = pagy.label_for(page), classes: nil, aria_label: nil|
-        classes    = %( class="#{classes}") if classes
-        aria_label = %( aria-label="#{aria_label}") if aria_label
-        %(#{left}#{page}#{right}#{classes}#{aria_label}>#{text}</a>)
-      end
-    end
-
     # Similar to I18n.t: just ~18x faster using ~10x less memory
     # (@pagy_locale explicitly initialized in order to avoid warning)
-    def pagy_t(key, opts = {})
-      Pagy::I18n.translate(@pagy_locale ||= nil, key, opts)
+    def pagy_t(key, **opts)
+      Pagy::I18n.translate(@pagy_locale ||= nil, key, **opts)
     end
 
     private
@@ -90,7 +92,7 @@ class Pagy
       if (p_next = pagy.next)
         a.(p_next, text, aria_label:)
       else
-        %(<a role="link" aria-disabled="true" aria-label=#{aria_label}>#{text}</a>)
+        %(<a role="link" aria-disabled="true" aria-label="#{aria_label}">#{text}</a>)
       end
     end
   end

data/lib/pagy/i18n.rb

@@ -154,7 +154,7 @@ class Pagy
     end
 
     # Translate and pluralize the key with the locale DATA
-    def translate(locale, key, opts = {})
+    def translate(locale, key, **opts)
       data, pluralize = DATA[locale]
       translation = data[key] || (opts[:count] && data[key += ".#{pluralize.call(opts[:count])}"]) \
                       or return %([translation missing: "#{key}"])

data/lib/pagy/keyset/active_record.rb

@@ -0,0 +1,38 @@
+# See Pagy API documentation: https://ddnexus.github.io/pagy/docs/api/keyset
+# frozen_string_literal: true
+
+class Pagy
+  class Keyset
+    # Keyset adapter for ActiveRecord
+    class ActiveRecord < Keyset
+      protected
+
+      # Get the keyset attributes of the record
+      def latest_from(latest_record) = latest_record.slice(*@keyset.keys)
+
+      # Extract the keyset from the set
+      def extract_keyset
+        @set.order_values.each_with_object({}) do |node, keyset|
+          keyset[node.value.name.to_sym] = node.direction
+        end
+      end
+
+      # Filter out the already retrieved records
+      def after_latest = @set.where(after_latest_query, **@latest)
+
+      # Append the missing keyset keys if the set is restricted by select
+      def apply_select
+        @set.select(*@keyset.keys)
+      end
+
+      # Set with selected columns?
+      def select? = !@set.select_values.empty?
+
+      # Typecast the latest attributes
+      def typecast_latest(latest)
+        @set.model.new(latest).slice(latest.keys)
+            .to_hash.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/pagy/keyset/sequel.rb

@@ -0,0 +1,51 @@
+# See Pagy API documentation: https://ddnexus.github.io/pagy/docs/api/keyset
+# frozen_string_literal: true
+
+class Pagy
+  class Keyset
+    # Keyset adapter for sequel
+    class Sequel < Keyset
+      protected
+
+      # Get the keyset attributes of the latest record
+      def latest_from(latest_record) = latest_record.to_hash.slice(*@keyset.keys)
+
+      # Extract the keyset from the set
+      def extract_keyset
+        return {} unless @set.opts[:order]
+
+        @set.opts[:order].each_with_object({}) do |item, keyset|
+          case item
+          when Symbol
+            keyset[item] = :asc
+          when ::Sequel::SQL::OrderedExpression
+            keyset[item.expression] = item.descending ? :desc : :asc
+          else
+            raise TypeError, "#{item.class.inspect} is not a supported Sequel::SQL::OrderedExpression"
+          end
+        end
+      end
+
+      # Filter out the already retrieved records
+      def after_latest = @set.where(::Sequel.lit(after_latest_query, **@latest))
+
+      # Append the missing keyset keys if the set is restricted by select
+      def apply_select
+        selected = @set.opts[:select]
+        @set.select_append(*@keyset.keys.reject { |c| selected.include?(c) })
+      end
+
+      # Set with selected columns?
+      def select? = !@set.opts[:select].nil?
+
+      # Typecast the latest attributes
+      def typecast_latest(latest)
+        model = @set.opts[:model]
+        model.unrestrict_primary_key if (restricted_pk = model.restrict_primary_key?)
+        latest = model.new(latest).to_hash.slice(*latest.keys.map(&:to_sym))
+        model.restrict_primary_key if restricted_pk
+        latest
+      end
+    end
+  end
+end

data/lib/pagy/keyset.rb

@@ -0,0 +1,99 @@
+# See Pagy API documentation: https://ddnexus.github.io/pagy/docs/api/keyset
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'b64'
+
+class Pagy
+  # Implement wicked-fast keyset pagination for big data
+  class Keyset
+    class TypeError < ::TypeError; end
+
+    include SharedMethods
+
+    # Pick the right adapter for the set
+    def self.new(set, **vars)
+      if self == Pagy::Keyset
+        if defined?(::ActiveRecord) && set.is_a?(::ActiveRecord::Relation)
+          ActiveRecord
+        elsif defined?(::Sequel) && set.is_a?(::Sequel::Dataset)
+          Sequel
+        else
+          raise TypeError, "expected set to be an instance of ActiveRecord::Relation or Sequel::Dataset; got #{set.class}"
+        end.new(set, **vars)
+      else
+        allocate.tap { |instance| instance.send(:initialize, set, **vars) }
+      end
+    end
+
+    attr_reader :latest  # Other readers from SharedMethods
+
+    def initialize(set, **vars)
+      default = DEFAULT.slice(:limit, :page_param,                    # from pagy
+                              :headers,                               # from headers extra
+                              :jsonapi,                               # from jsonapi extra
+                              :limit_param, :limit_max, :limit_extra) # from limit_extra
+      assign_vars({ **default, page: nil }, vars)
+      assign_limit
+      @set    = set
+      @page   = @vars[:page]
+      @keyset = extract_keyset
+      raise InternalError, 'the set must be ordered' if @keyset.empty?
+      return unless @page
+
+      latest  = JSON.parse(B64.urlsafe_decode(@page)).transform_keys(&:to_sym)
+      @latest = @vars[:typecast_latest]&.(latest) || typecast_latest(latest)
+      raise InternalError, 'page and keyset are not consistent' \
+            unless @latest.keys == @keyset.keys
+    end
+
+    # Return the next page
+    def next
+      records
+      return unless @more
+
+      @next ||= B64.urlsafe_encode(latest_from(@records.last).to_json)
+    end
+
+    # Retrieve the array of records for the current page
+    def records
+      @records ||= begin
+        @set    = apply_select if select?
+        @set    = @vars[:after_latest]&.(@set, @latest) || after_latest if @latest
+        records = @set.limit(@limit + 1).to_a
+        @more   = records.size > @limit && !records.pop.nil?
+        records
+      end
+    end
+
+    protected
+
+    # Prepare the literal query to filter out the already retrieved records
+    def after_latest_query
+      operator   = { asc: '>', desc: '<' }
+      directions = @keyset.values
+      if @vars[:row_comparison]
+        # Row comparison: check if your DB supports it (especially if you have mixed order rows)
+        columns      = @keyset.keys
+        placeholders = columns.map { |column| ":#{column}" }.join(', ')
+        "( #{columns.join(', ')} ) #{operator[directions.first]} ( #{placeholders} )"
+      else
+        # Generic comparison: works for keysets ordered in mixed or same directions
+        keyset = @keyset.to_a
+        where  = []
+        until keyset.empty?
+          last_column, last_direction = keyset.pop
+          query = +'( '
+          query << (keyset.map { |column, _d| "#{column} = :#{column}" } \
+                    << "#{last_column} #{operator[last_direction]} :#{last_column}").join(' AND ')
+          query << ' )'
+          where << query
+        end
+        where.join(' OR ')
+      end
+    end
+  end
+end
+
+require_relative 'keyset/active_record'
+require_relative 'keyset/sequel'

data/lib/pagy/url_helpers.rb

@@ -6,21 +6,21 @@ class Pagy
     # 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: false, **_)
+    def pagy_url_for(pagy, page, absolute: false, fragment: nil, **_)
       vars         = pagy.vars
-      pagy_params  = pagy.params.is_a?(Hash) ? pagy.params.transform_keys(&:to_s) : {}
-      params       = request.GET.merge(pagy_params)
-      pagy_set_query_params(page, vars, params)
-      params       = pagy.params.call(params) if pagy.params.is_a?(Proc)
-      query_string = "?#{Rack::Utils.build_nested_query(params)}"
-      "#{request.base_url if absolute}#{vars[:request_path] || request.path}#{query_string}#{vars[:fragment]}"
+      query_params = request.GET.clone
+      query_params.merge!(vars[:params].transform_keys(&:to_s)) if vars[:params].is_a?(Hash)
+      pagy_set_query_params(page, vars, query_params)
+      query_params = vars[:params].(query_params) if vars[:params].is_a?(Proc)
+      query_string = "?#{Rack::Utils.build_nested_query(query_params)}"
+      "#{request.base_url if absolute}#{vars[:request_path] || request.path}#{query_string}#{fragment}"
     end
 
-    # Add the page and items params
+    # Add the page and limit params
     # Overridable by the jsonapi extra
-    def pagy_set_query_params(page, vars, params)
-      params[vars[:page_param].to_s]  = page
-      params[vars[:items_param].to_s] = vars[:items] if vars[:items_extra]
+    def pagy_set_query_params(page, vars, query_params)
+      query_params[vars[:page_param].to_s]  = page if page
+      query_params[vars[:limit_param].to_s] = vars[:limit] if vars[:limit_extra]
     end
   end
 end