pagy 43.0.0 → 43.3.0

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

@@ -6,37 +6,57 @@ require_relative '../../modules/b64'
 class Pagy
   # Implement wicked-fast keyset pagination for big data
   class Keyset < Pagy
-    path = Pathname.new(__dir__)
-    autoload :ActiveRecord, path.join('active_record')
-    autoload :Sequel,       path.join('sequel')
-    autoload :Keynav,       path.join('keynav')
+    # Autoload adapters: files are loaded only when const_get accesses them
+    module Adapters
+      path = Pathname.new(__dir__)
+      autoload :ActiveRecord, path.join('adapters/active_record')
+      autoload :Sequel,       path.join('adapters/sequel')
+    end
+
+    autoload :Keynav, Pathname.new(__dir__).join('keynav')
+
+    # Define empty subclasses to allow specific typing without triggering autoload
+    class ActiveRecord < self; end
+    class Sequel       < self; end
 
     class TypeError < ::TypeError; end
 
-    # Initialize Keyset* and Keyset::Keynav* classes and subclasses
+    # Factory method: detects the set type, configures the subclass, and instantiates
     def self.new(set, **)
-      # Subclass instances run only the initializer
-      if /::(?:ActiveRecord|Sequel)$/.match?(name)  # check without triggering autoload
-        return allocate.tap { |instance| instance.send(:initialize, set, **) }
+      # 1. Handle direct subclass usage (e.g. Pagy::Keyset::ActiveRecord.new)
+      if /::(?:ActiveRecord|Sequel)$/.match?(name)
+        # Ensure the adapter is mixed in (lazy load)
+        mix_in_adapter(name.split('::').last)
+        return allocate.tap { _1.send(:initialize, set, **) }
       end
 
-      subclass = if defined?(::ActiveRecord) && set.is_a?(::ActiveRecord::Relation)
-                   self::ActiveRecord
-                 elsif defined?(::Sequel) && set.is_a?(::Sequel::Dataset)
-                   self::Sequel
-                 else
-                   raise TypeError, "expected an ActiveRecord::Relation or Sequel::Dataset; got #{set.class}"
-                 end
-      subclass.new(set, **)
+      # 2. Handle Factory usage (Pagy::Keyset.new)
+      adapter = if defined?(::ActiveRecord) && set.is_a?(::ActiveRecord::Relation)
+                  :ActiveRecord
+                elsif defined?(::Sequel) && set.is_a?(::Sequel::Dataset)
+                  :Sequel
+                else
+                  raise TypeError, "expected an ActiveRecord::Relation or Sequel::Dataset; got #{set.class}"
+                end
+
+      const_get(adapter).tap { _1.mix_in_adapter(adapter) }.new(set, **)
+    end
+
+    # Helper to lazy-include the adapter module
+    def self.mix_in_adapter(adapter)
+      adapter_module = Adapters.const_get(adapter)
+      include(adapter_module) unless self < adapter_module
     end
 
-    def initialize(set, **) # rubocop:disable Lint/MissingSuper
+    def initialize(set, **)
       assign_options(**)
       assign_and_check(limit: 1)
       @set    = set
       @keyset = @options[:keyset] || extract_keyset
       raise InternalError, 'the set must be ordered' if @keyset.empty?
 
+      @identifiers = quoted_identifiers(@set.model.table_name)
+
       assign_page
       self.next
     end
@@ -91,23 +111,28 @@ class Pagy
     def compose_predicate(prefix = nil)
       operator    = { asc: '>', desc: '<' }
       directions  = @keyset.values
-      identifier  = quoted_identifiers(@set.model.table_name)
+      identifier  = @identifiers
       placeholder = @keyset.to_h { |column| [column, ":#{prefix}#{column}"] }
-      if @options[:tuple_comparison] && (directions.all?(:asc) || directions.all?(:desc))
-        "(#{identifier.values.join(', ')}) #{operator[directions.first]} (#{placeholder.values.join(', ')})"
-      else
-        keyset = @keyset.to_a
-        union  = []
-        until keyset.empty?
-          last_column, last_direction = keyset.pop
-          intersection = +'('
-          intersection << (keyset.map { |column, _d| "#{identifier[column]} = #{placeholder[column]}" } \
-                            << "#{identifier[last_column]} #{operator[last_direction]} #{placeholder[last_column]}").join(' AND ')
-          intersection << ')'
-          union << intersection
-        end
-        union.join(' OR ')
+
+      return "(#{identifier.values.join(', ')}) #{operator[directions.first]} (#{placeholder.values.join(', ')})" \
+             if @options[:tuple_comparison] && (directions.all?(:asc) || directions.all?(:desc))
+
+      keyset = @keyset.to_a
+      ors    = []
+      until keyset.empty?
+        column, direction = keyset.pop
+        ands = keyset.map { |k, _| "#{identifier[k]} = #{placeholder[k]}" }
+        ands << "#{identifier[column]} #{operator[direction]} #{placeholder[column]}"
+        ors << "(#{ands.join(' AND ')})"
       end
+      query = ors.join(' OR ')
+
+      return query unless @keyset.size > 1
+
+      # Add hint predicate for DB optimizers that struggle with ORs
+      column, direction = @keyset.first
+      hint = "#{identifier[column]} #{operator[direction]}= #{placeholder[column]}"
+      "#{hint} AND (#{query})"
     end
 
     # Return the prefixed arguments from a cutoff

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

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Offset
+    # Offset pagination with memoized count
+    class Countish < Offset
+      protected
+
+      # Return page+count or page+count+epoch
+      def compose_page_param(page)
+        value  = "#{page || 1}+#{@count}"
+        value << "+#{@options[:epoch]}" if @options[:epoch]
+        EscapedValue.new(value)
+      end
+    end
+  end
+end

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

@@ -4,11 +4,11 @@ class Pagy
   class Offset
     # Offset pagination without a count
     class Countless < Offset
-      def initialize(**) # rubocop:disable Lint/MissingSuper
+      def initialize(**)
         assign_options(**)
         assign_and_check(limit: 1, page: 1)
         @page = upto_max_pages(@page)
-        assign_last
+        @last = upto_max_pages(@options[:last]) unless @options[:headless]
         assign_offset
       end
 
@@ -25,32 +25,44 @@ class Pagy
       def countless? = true
 
       def upto_max_pages(value)
-        return value unless @options[:max_pages]
+        return value unless value && @options[:max_pages]
 
         [value, @options[:max_pages]].min
       end
 
-      def assign_last
-        return unless @options[:last]
-
-        @last = upto_max_pages(@options[:last].to_i)
-      end
-
       # Finalize the instance variables based on the fetched size
       def finalize(fetched_size)
-        return self unless in_range? { fetched_size.positive? || @page == 1 }
+        # empty records (trigger the right info message for known 0 count)
+        @count = 0 if fetched_size.zero? && @page == 1
 
-        if @last && @page < @last # visited page
-          @last = @page unless fetched_size > @limit # set last if last page
-        else
-          @last = upto_max_pages(fetched_size > @limit ? @page + 1 : @page)
+        unless in_range? { fetched_size.positive? || @page == 1 }
+          assign_empty_page_variables
+          return self
         end
+
+        past  = @last && @page < @last # current page is before the known last page
+        more  = fetched_size > @limit  # more pages after this one
+        @last = upto_max_pages(more ? @page + 1 : @page) unless past && more
         @in   = [fetched_size, @limit].min
         @from = @in.zero? ? 0 : @offset + 1
         @to   = @offset + @in
         assign_previous_and_next
+
         self
       end
+
+      # Called by false in_range?
+      def assign_empty_page_variables
+        @in = @from = @to = 0
+        target_last = [@page - 1, 1].max
+        @last       = [@last || target_last, target_last].min
+        @previous   = @last
+      end
+
+      # Support easy countless page param overriding (for legacy param and behavior)
+      def compose_page_param(page)
+        EscapedValue.new("#{page || 1}+#{@last}")
+      end
     end
   end
 end

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

@@ -9,20 +9,26 @@ class Pagy
     DEFAULT = { page: 1 }.freeze
 
     autoload :Countless, Pathname.new(__dir__).join('countless')
+    autoload :Countish,  Pathname.new(__dir__).join('countish')
 
     include Rangeable
     include Shiftable
 
-    def initialize(**) # rubocop:disable Lint/MissingSuper
+    def initialize(**)
       assign_options(**)
       assign_and_check(limit: 1, count: 0, page: 1)
       assign_last
       assign_offset
-      return unless in_range? { @page <= @last }
+
+      unless in_range? { @page <= @last }
+        assign_empty_page_variables
+        return
+      end
 
       @from = [@offset + 1, @count].min
       @to   = [@offset + @limit, @count].min
       @in   = [@to - @from + 1, @count].min
+
       assign_previous_and_next
     end
 

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

@@ -3,14 +3,14 @@
 class Pagy
   module Search
     class Arguments < Array
-      def respond_to_missing? = true
+      def respond_to_missing?(*) = true
 
       def method_missing(*) = push(*)
     end
 
     # Collect the search arguments to pass to the actual search
-    def pagy_search(term = nil, **options, &block)
-      Arguments.new([self, term, options, block])
+    def pagy_search(*arguments, **options, &block)
+      Arguments.new([self, arguments, options, block])
     end
   end
 
@@ -22,17 +22,13 @@ class Pagy
     def search? = true
   end
 
-  class ElasticsearchRails < SearchBase
-    # Get the count from different versions of ElasticsearchRails
-    def self.total_count(results)
-      total = results.instance_eval { respond_to?(:raw_response) ? raw_response['hits']['total'] : response['hits']['total'] }
-      total.is_a?(Hash) ? total['value'] : total
-    end
-  end
+  class ElasticsearchRails < SearchBase; end
 
   class Meilisearch < SearchBase
     DEFAULT = { search_method: :ms_search }.freeze
   end
 
   class Searchkick < SearchBase; end
+
+  class TypesenseRails < SearchBase; end
 end

data/lib/pagy/classes/request.rb

@@ -1,36 +1,45 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Decouple the reuest from the env, allowing non-rack apps to use pagy by passing a hash.
-  # Resolve :page and :limit, supporting the :jsonapi option. Support for URL composition.
+  # Decouple the request from the env, allowing non-rack apps to use pagy by passing a hash.
+  # Resolve the :page and :limit options from params.
   class Request
-    def initialize(request, options = {})
-      @base_url, @path, @query, @cookie =
+    def initialize(options)
+      @options = options
+      request  = @options[:request]
+      @base_url, @path, @params, @cookie =
         if request.is_a?(Hash)
-          request.values_at(:base_url, :path, :query, :cookie)
+          request.values_at(:base_url, :path, :params, :cookie)
         else
-          [request.base_url, request.path, request.GET, request.cookies['pagy']]
+          [request.base_url, request.path, get_params(request), request.cookies['pagy']]
         end
-      @jsonapi = @query['page'] && options[:jsonapi]
-      raise JsonapiReservedParamError, @query['page'] if @jsonapi && !@query['page'].respond_to?(:fetch)
+      freeze
     end
 
-    attr_reader :base_url, :path, :query, :cookie
+    attr_reader :base_url, :path, :params, :cookie
 
-    def resolve_page(options, force_integer: true)
-      page_key = options[:page_key] || DEFAULT[:page_key]
-      page     = @jsonapi ? @query['page'][page_key] : @query[page_key]
-      page     = nil if page == ''   # fix for app-generated queries like ?page=
-      force_integer ? (page || 1).to_i : page
+    def resolve_page(force_integer: true)
+      page_key = @options[:page_key] || DEFAULT[:page_key]
+      page     = @params.dig(@options[:root_key], page_key) || @params[page_key]
+      return [page.to_s.to_i, 1].max if force_integer
+
+      page unless page == ''
+    end
+
+    def resolve_limit
+      default   = @options[:limit] || DEFAULT[:limit]
+      max_limit = @options[:client_max_limit]
+      return default unless max_limit
+
+      limit_key = @options[:limit_key] || DEFAULT[:limit_key]
+      limit     = (@params.dig(@options[:root_key], limit_key) || @params[limit_key]).to_s.to_i
+      limit.zero? ? default : [limit, max_limit].min
     end
 
-    def resolve_limit(options)
-      limit_key = options[:limit_key] || DEFAULT[:limit_key]
-      return options[:limit] || DEFAULT[:limit] \
-             unless options[:client_max_limit] &&
-                    (requested_limit = @jsonapi ? @query['page'][limit_key] : @query[limit_key])
+    private
 
-      [requested_limit.to_i, options[:client_max_limit]].min
+    def get_params(request)
+      request.GET.merge(request.POST).to_h.freeze
     end
   end
 end

data/lib/pagy/cli.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'optparse'
+require 'fileutils'
+require 'rbconfig'
+require_relative '../pagy'
+require_relative '../../apps/index'
+
+class Pagy
+  class CLI
+    HOST  = 'localhost'
+    PORT  = '8000'
+
+    def start(args = ARGV)
+      options = parse_options(args)
+      run_command(args, options)
+    end
+
+    private
+
+    def parse_options(args)
+      options = { env: 'development', host: HOST, port: PORT, quiet: false }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = <<~BANNER
+          Pagy #{VERSION} (https://ddnexus.github.io/pagy/playground)
+          Playground to showcase, clone and develop Pagy APPs
+
+          Usage:
+            pagy APP [opts]   Showcase APP from the installed gem
+            pagy clone APP    Clone APP to the current dir
+            pagy FILE [opts]  Develop app FILE from local path
+        BANNER
+
+        opts.summary_indent = '  '
+        opts.summary_width  = 18
+
+        opts.separator "\nAPPs"
+        PagyApps::INDEX.each do |name, path|
+          desc = File.readlines(path)[3].sub('#    ', '').strip
+          opts.separator "  #{name.ljust(18)}#{desc}"
+        end
+
+        opts.separator "\nRackup options"
+        opts.on('-e', '--env ENV', 'Environment')     { |v| options[:env] = v }
+        opts.on('-o', '--host HOST', 'Host')          { |v| options[:host] = v }
+        opts.on('-p', '--port PORT', 'Port')          { |v| options[:port] = v }
+        opts.on('-t', '--threads THREADS', 'Threads') { |v| options[:threads] = v }
+
+        opts.separator "\nOther options"
+        opts.on('-q', '--quiet', 'Quiet mode for development') { options[:quiet] = true }
+        opts.on('-v', '--version', 'Show version') do
+          puts VERSION
+          exit
+        end
+        opts.on('-h', '--help', 'Show this help') do
+          puts opts
+          exit
+        end
+
+        opts.separator "\nExamples"
+        opts.separator "  pagy demo          Showcase demo at http://#{HOST}:#{PORT}"
+        opts.separator '  pagy clone repro   Clone repro to ./repro.ru (rename it)'
+        opts.separator "  pagy ~/myapp.ru    Develop ~/myapp.ru at #{HOST}:#{PORT}"
+      end
+
+      begin
+        parser.parse!(args)
+      rescue OptionParser::InvalidOption => e
+        abort e.message
+      end
+
+      if args.empty?
+        puts parser
+        exit
+      end
+
+      options
+    end
+
+    def run_command(args, options)
+      run_from_repo = Pagy::ROOT.join('pagy.gemspec').exist?
+      setup_gems(run_from_repo)
+
+      arg = args.shift
+
+      if arg.eql?('clone')
+        clone_app(args.shift)
+      else
+        serve_app(arg, options)
+      end
+    end
+
+    def clone_app(name)
+      abort "Expected APP to be in [#{PagyApps::INDEX.keys.join(', ')}]; got #{name.inspect}" unless PagyApps::INDEX.key?(name)
+
+      if File.exist?(name)
+        print "Do you want to overwrite the #{name.inspect} file? (y/n)> "
+        answer = gets.chomp
+        abort "#{name.inspect} file already present" unless answer.start_with?(/y/i)
+      end
+      FileUtils.cp(PagyApps::INDEX[name], '.', verbose: true)
+    end
+
+    def serve_app(arg, options)
+      if PagyApps::INDEX.key?(arg)
+        options[:env]   = 'showcase'
+        options[:quiet] = true
+        # Avoid the creation of './tmp/local_secret.txt' for showcase env
+        ENV['SECRET_KEY_BASE'] = 'absolute secret!' if arg.eql?('rails')
+        file = PagyApps::INDEX[arg]
+      else
+        file = arg
+      end
+      abort "#{file.inspect} app not found" unless File.exist?(file)
+
+      gem_dir = File.expand_path('../..', __dir__)
+      rackup  = "rackup -I #{gem_dir}/lib -r pagy -o #{options[:host]} -p #{options[:port]} -E #{options[:env]} #{file}"
+      rackup << " -O Threads=#{options[:threads]}" if options[:threads]
+      rackup << ' -q' if options[:quiet]
+
+      exec(rackup)
+    end
+
+    # Kept as a separate method because mocking 'gemfile' (dsl) is complex otherwise
+    def setup_gems(run_from_repo)
+      require 'bundler/inline'
+      gemfile(!run_from_repo) do
+        source 'https://rubygems.org'
+        gem 'logger'
+        gem 'rackup'
+      end
+    end
+  end
+end

data/lib/pagy/console.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Console loader
+
+require 'pagy'
+include Pagy::Console # rubocop:disable Style/MixinUsage

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

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class Pagy
-  # Add configurstion methods
+  # Add configuration methods
   module Configurable
     # Sync the pagy javascript targets
     def sync_javascript(destination, *targets)
@@ -15,7 +15,7 @@ class Pagy
     def dev_tools(wand_scale: 1)
       <<~HTML
         <script id="pagy-ai-widget">
-          document.addEventListener('wand-positioned', #{ROOT.join('javascripts/ai_widget.js').read});
+          #{ROOT.join('javascripts/ai_widget.js').read}
         </script>
         <script id="pagy-wand" data-scale="#{wand_scale}">
           #{ROOT.join('javascripts/wand.js').read}

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Provide the helpers to count a collection
+  module Countable
+    module_function
+
+    # Get the collection count
+    def get_count(collection, options)
+      return collection.size if collection.instance_of?(Array)
+      return collection.count unless defined?(::ActiveRecord) && collection.is_a?(::ActiveRecord::Relation)
+
+      count = if options[:count_over] && !collection.group_values.empty?
+                # COUNT(*) OVER ()
+                sql = Arel.star.count.over(Arel::Nodes::Grouping.new([]))
+                collection.unscope(:order).pick(sql).to_i
+              else
+                collection.count(:all)
+              end
+
+      count.is_a?(Hash) ? count.size : count
+    end
+  end
+end

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

@@ -3,31 +3,31 @@
 require 'uri'
 
 class Pagy
+  # Support spaces in placeholder params
+  class EscapedValue < String; end
+
   # Provide the helpers to handle the url and anchor
   module Linkable
     module QueryUtils
       module_function
 
       # Extracted from Rack::Utils and reformatted for rubocop
-      # Add the 'unescaped' param, and use it for simple and safe url-templating.
-      # All string keyed hashes
-      def build_nested_query(value, prefix = nil, unescaped = [])
+      # Allow unescaped Pagy::RawQueryValue
+      def build_nested_query(value, prefix = nil)
         case value
         when Array
-          value.map { |v| build_nested_query(v, "#{prefix}[]", unescaped) }.join('&')
+          value.map { |v| build_nested_query(v, "#{prefix}[]") }.join('&')
         when Hash
           value.map do |k, v|
-            new_k = prefix ? "#{prefix}[#{escape(k)}]" : escape(k)
-            unescaped[unescaped.find_index(k)] = new_k if unescaped.size.positive? && new_k != k && unescaped.include?(k)
-            build_nested_query(v, new_k, unescaped)
+            build_nested_query(v, prefix ? "#{prefix}[#{k}]" : k)
           end.delete_if(&:empty?).join('&')
         when nil
           escape(prefix)
         else
           raise ArgumentError, 'value must be a Hash' if prefix.nil?
-          return "#{escape(prefix)}=#{value}" if unescaped.include?(prefix)
 
-          "#{escape(prefix)}=#{escape(value)}"
+          escaped_value = value.is_a?(EscapedValue) ? value : escape(value)
+          "#{escape(prefix)}=#{escaped_value}"
         end
       end
 
@@ -38,22 +38,33 @@ class Pagy
 
     protected
 
+    # Overridable by classes with composite page param
+    def compose_page_param(page) = page
+
     # Return the URL for the page, relying on the Pagy::Request
-    def compose_page_url(page, limit_token: nil, **options)
-      jsonapi, page_key, limit_key, limit, client_max_limit, querify, absolute, path, fragment =
-        @options.merge(options)
-                .values_at(:jsonapi, :page_key, :limit_key, :limit, :client_max_limit, :querify, :absolute, :path, :fragment)
-      query = @request.query.clone(freeze: false)
-      query.delete(jsonapi ? 'page' : page_key)
-      factors = {}.tap do |h|
-                  h[page_key]  = countless? ? "#{page || 1}+#{@last}" : page
-                  h[limit_key] = limit_token || limit if client_max_limit
-                end.compact # No empty params
-      query.merge!(jsonapi ? { 'page' => factors } : factors) if factors.size.positive?
-      querify&.(query) # Must modify the query: the returned value is ignored
-      query_string = QueryUtils.build_nested_query(query, nil, [page_key, limit_key])
-      query_string = "?#{query_string}" unless query_string.empty?
-      fragment   &&= %(##{fragment}) unless fragment&.start_with?('#')
+    def compose_page_url(page, **options)
+      opts      = @options.merge(options)
+      params    = @request.params.clone(freeze: false)
+      root_key  = opts[:root_key]
+      container = if root_key
+                    params[root_key] = params[root_key]&.clone(freeze: false) || {}
+                  else
+                    params
+                  end
+
+      { opts[:page_key]  => compose_page_param(page),
+        opts[:limit_key] => opts[:client_max_limit] && opts[:limit] }.each do |k, v|
+        v ? container[k] = v : container.delete(k)
+      end
+
+      opts[:querify]&.(params) # Must modify the params: the returned value is ignored
+      fragment = opts[:fragment].to_s.sub(/\A(?=[^#])/, '#') # conditionally prepend '#'
+
+      compose_url(opts[:absolute], opts[:path], params, fragment)
+    end
+
+    def compose_url(absolute, path, params, fragment)
+      query_string = QueryUtils.build_nested_query(params).sub(/\A(?=.)/, '?') # conditionally prepend '?'
       "#{@request.base_url if absolute}#{path || @request.path}#{query_string}#{fragment}"
     end
   end

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

@@ -5,11 +5,11 @@ class Pagy
   module Rangeable
     # Check if in range
     def in_range?
-      return @in_range if defined?(@in_range) || (@in_range = yield)
+      return @in_range if defined?(@in_range)
+      return true if (@in_range = yield)
       raise RangeError.new(self, :page, "in 1..#{@last}", @page) if @options[:raise_range_error]
 
-      assign_empty_page_variables
-      false
+      @in_range = false
     end
   end
 end

data/lib/pagy/modules/b64.rb

@@ -5,14 +5,19 @@ class Pagy
   module B64
     module_function
 
-    def encode(bin) = [bin].pack('m0')
+    def encode(bin)
+      [bin].pack('m0')
+    end
 
-    def decode(str) = str.unpack1('m0')
+    def decode(str)
+      str.unpack1('m0')
+    end
 
     def urlsafe_encode(bin)
       str = encode(bin)
-      str.chomp!('==') or str.chomp!('=')
       str.tr!('+/', '-_')
+      str.delete!('=')
+
       str
     end
 
@@ -23,6 +28,7 @@ class Pagy
       else
         str = str.tr('-_', '+/')
       end
+
       decode(str)
     end
   end