pagy 8.6.0 → 9.0.2

data/lib/pagy/extras/pagy.rb

@@ -12,7 +12,7 @@ class Pagy # :nodoc:
     def pagy_nav_js(pagy, id: nil, aria_label: nil, **vars)
       sequels = pagy.sequels(**vars)
       id      = %( id="#{id}") if id
-      a       = pagy_anchor(pagy)
+      a       = pagy_anchor(pagy, **vars)
       tokens  = { 'before'  => prev_a(pagy, a),
                   'a'       => a.(PAGE_TOKEN, LABEL_TOKEN),
                   'current' => %(<a class="current" role="link" aria-current="page" aria-disabled="true">#{
@@ -27,9 +27,9 @@ class Pagy # :nodoc:
     end
 
     # Javascript combo pagination: it returns a nav with a data-pagy attribute used by the pagy.js file
-    def pagy_combo_nav_js(pagy, id: nil, aria_label: nil)
+    def pagy_combo_nav_js(pagy, id: nil, aria_label: nil, **vars)
       id    = %( id="#{id}") if id
-      a     = pagy_anchor(pagy)
+      a     = pagy_anchor(pagy, **vars)
       pages = pagy.pages
 
       page_input = %(<input name="page" type="number" min="1" max="#{pages}" value="#{pagy.page}" aria-current="page" ) <<
@@ -37,7 +37,7 @@ class Pagy # :nodoc:
 
       %(<nav#{id} class="pagy combo-nav-js" #{
           nav_aria_label(pagy, aria_label:)} #{
-          pagy_data(pagy, :combo, pagy_url_for(pagy, PAGE_TOKEN))}>#{
+          pagy_data(pagy, :combo, pagy_url_for(pagy, PAGE_TOKEN, **vars))}>#{
           prev_a(pagy, a)
         }<label>#{
           pagy_t('pagy.combo_nav_js', page_input:, pages:)
@@ -47,35 +47,35 @@ class Pagy # :nodoc:
     end
 
     # Return the previous page URL string or nil
-    def pagy_prev_url(pagy, absolute: false)
-      pagy_url_for(pagy, pagy.prev, absolute:) if pagy.prev
+    def pagy_prev_url(pagy, **vars)
+      pagy_url_for(pagy, pagy.prev, **vars) if pagy.prev
     end
 
     # Return the next page URL string or nil
-    def pagy_next_url(pagy, absolute: false)
-      pagy_url_for(pagy, pagy.next, absolute:) if pagy.next
+    def pagy_next_url(pagy, **vars)
+      pagy_url_for(pagy, pagy.next, **vars) if pagy.next
     end
 
     # Return the enabled/disabled previous page anchor tag
-    def pagy_prev_a(pagy, text: pagy_t('pagy.prev'), aria_label: pagy_t('pagy.aria_label.prev'))
-      a = pagy_anchor(pagy)
+    def pagy_prev_a(pagy, text: pagy_t('pagy.prev'), aria_label: pagy_t('pagy.aria_label.prev'), **vars)
+      a = pagy_anchor(pagy, **vars)
       prev_a(pagy, a, text:, aria_label:)
     end
 
     # Return the enabled/disabled next page anchor tag
-    def pagy_next_a(pagy, text: pagy_t('pagy.next'), aria_label: pagy_t('pagy.aria_label.next'))
-      a = pagy_anchor(pagy)
+    def pagy_next_a(pagy, text: pagy_t('pagy.next'), aria_label: pagy_t('pagy.aria_label.next'), **vars)
+      a = pagy_anchor(pagy, **vars)
       next_a(pagy, a, text:, aria_label:)
     end
 
     # Conditionally return the previous page link tag
-    def pagy_prev_link(pagy, absolute: false)
-      %(<link href="#{pagy_url_for(pagy, pagy.prev, absolute:)}"/>) if pagy.prev
+    def pagy_prev_link(pagy, **vars)
+      %(<link href="#{pagy_url_for(pagy, pagy.prev, **vars)}"/>) if pagy.prev
     end
 
     # Conditionally return the next page link tag
-    def pagy_next_link(pagy, absolute: false)
-      %(<link href="#{pagy_url_for(pagy, pagy.next, absolute:)}"/>) if pagy.next
+    def pagy_next_link(pagy, **vars)
+      %(<link href="#{pagy_url_for(pagy, pagy.next, **vars)}"/>) if pagy.next
     end
   end
   Frontend.prepend PagyExtra

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

@@ -5,11 +5,11 @@ 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
-    # Setup @items based on the :gearbox_items variable
+    # 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 size 4 || 0', 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|

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,13 +28,17 @@ 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
@@ -46,7 +46,7 @@ class Pagy # :nodoc:
       pagy_set_query_params(page, vars, params)
       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,9 +6,9 @@ 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)
+    def pagy_anchor(pagy, **_)
       a_proc = super
       return a_proc unless pagy.vars[:trim_extra]
 

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_relative 'url_helpers'
 require_relative 'i18n'
+require_relative 'url_helpers'
 
 class Pagy
   # Used for search and replace, hardcoded also in the pagy.js file
@@ -14,26 +14,17 @@ class Pagy
   module Frontend
     include UrlHelpers
 
-    # Generic pagination: it returns the html with the series of links to the pages
-    def pagy_nav(pagy, id: nil, aria_label: nil, **vars)
-      id = %( id="#{id}") if id
-      a  = pagy_anchor(pagy)
-
-      html = %(<nav#{id} class="pagy nav" #{nav_aria_label(pagy, aria_label:)}>#{
-                 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
-                  a.(item)
-                when String
-                  %(<a role="link" aria-disabled="true" aria-current="page" class="current">#{pagy.label_for(item)}</a>)
-                when :gap
-                  %(<a role="link" aria-disabled="true" class="gap">#{pagy_t('pagy.gap')}</a>)
-                else
-                  raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
-                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, 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
-      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"
@@ -54,24 +45,32 @@ class Pagy
         }</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>)
+    # Generic pagination: it returns the html with the series of links to the pages
+    def pagy_nav(pagy, id: nil, aria_label: nil, anchor_string: nil, **vars)
+      id = %( id="#{id}") if id
+      a  = pagy_anchor(pagy, anchor_string:)
+
+      html = %(<nav#{id} class="pagy nav" #{nav_aria_label(pagy, aria_label:)}>#{
+                 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
+                  a.(item)
+                when String
+                  %(<a role="link" aria-disabled="true" aria-current="page" class="current">#{pagy.label_for(item)}</a>)
+                when :gap
+                  %(<a role="link" aria-disabled="true" class="gap">#{pagy_t('pagy.gap')}</a>)
+                else
+                  raise InternalError, "expected item types in series to be Integer, String or :gap; got #{item.inspect}"
+                end
       end
+      html << %(#{next_a(pagy, a)}</nav>)
     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

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,98 @@
+# See Pagy API documentation: https://ddnexus.github.io/pagy/docs/api/keyset
+# frozen_string_literal: true
+
+require 'json'
+require_relative 'b64'
+require_relative 'shared_methods'
+
+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 fetched records
+    def after_latest_query
+      operator   = { asc: '>', desc: '<' }
+      directions = @keyset.values
+      if @vars[:tuple_comparison] && (directions.all?(:asc) || directions.all?(:desc))
+        columns      = @keyset.keys
+        placeholders = columns.map { |column| ":#{column}" }.join(', ')
+        "( #{columns.join(', ')} ) #{operator[directions.first]} ( #{placeholders} )"
+      else
+        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/shared_methods.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Shared with Keyset
+  module SharedMethods
+    attr_reader :page, :limit, :vars
+
+    # Validates and assign the passed vars: var must be present and value.to_i must be >= to min
+    def assign_and_check(name_min)
+      name_min.each do |name, min|
+        raise VariableError.new(self, name, ">= #{min}", @vars[name]) \
+        unless @vars[name]&.respond_to?(:to_i) && \
+               instance_variable_set(:"@#{name}", @vars[name].to_i) >= min
+      end
+    end
+
+    # Assign @limit (overridden by the gearbox extra)
+    def assign_limit
+      assign_and_check(limit: 1)
+    end
+
+    # Assign @vars
+    def assign_vars(default, vars)
+      @vars = { **default, **vars.delete_if { |k, v| default.key?(k) && (v.nil? || v == '') } }
+    end
+  end
+end

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
       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}#{vars[:fragment]}"
+      "#{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, query_params)
       query_params[vars[:page_param].to_s]  = page
-      query_params[vars[:items_param].to_s] = vars[:items] if vars[:items_extra]
+      query_params[vars[:limit_param].to_s] = vars[:limit] if vars[:limit_extra]
     end
   end
 end