pagy 7.0.11 → 43.5.1

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

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require 'json'
+require_relative '../../modules/b64'
+
+class Pagy
+  # Fast keyset pagination for big data
+  class Keyset < Pagy
+    # Autoload adapters 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
+
+    # Factory method: detect the set type, configure the subclass, and instantiate.
+    def self.new(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
+
+      # 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
+
+    # 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, **)
+      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
+
+    # The array of records for the current page
+    def records
+      @records ||= begin
+                     ensure_select
+                     fetch_records
+                   end
+    end
+
+    # The next page (i.e., the cutoff of the current page)
+    def next
+      records
+      return unless @more
+
+      @next ||= B64.urlsafe_encode(extract_cutoff.to_json)
+    end
+
+    protected
+
+    def keyset? = true
+
+    def assign_page
+      return unless (@page = @options[:page])
+
+      @prior_cutoff = JSON.parse(B64.urlsafe_decode(@page))
+    end
+
+    def fetch_records
+      apply_where(compose_predicate, arguments_from(@prior_cutoff)) if @prior_cutoff
+      @set.limit(@limit + 1).to_a.tap do |records|
+        @more = records.size > @limit && !records.pop.nil?
+      end
+    end
+
+    # Compose the parameterized predicate used to extract the page records.
+    #
+    # For example, with a set like Pet.order(animal: :asc, name: :desc, id: :asc)
+    # it returns a union of intersections:
+    #
+    #    ("pets"."animal" = :animal AND "pets"."name" = :name AND "pets"."id" > :id) OR
+    #    ("pets"."animal" = :animal AND "pets"."name" < :name) OR
+    #    ("pets"."animal" > :animal)
+    #
+    # When :tuple_comparison is enabled, and if the order is all :asc or all :desc,
+    # with a set like Pet.order(:animal, :name, :id) it returns the following string:
+    #
+    #     ("pets"."animal", "pets"."name", "pets"."id") > (:animal, :name, :id)
+    #
+    def compose_predicate(prefix = nil)
+      operator    = { asc: '>', desc: '<' }
+      directions  = @keyset.values
+      identifier  = @identifiers
+      placeholder = @keyset.to_h { |column| [column, ":#{prefix}#{column}"] }
+
+      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
+
+    # The prefixed arguments from a cutoff
+    def arguments_from(cutoff, prefix = nil)
+      attributes = typecast(@keyset.keys.zip(cutoff).to_h)
+      prefix ? attributes.transform_keys { |key| :"#{prefix}#{key}" } : attributes
+    end
+
+    def extract_cutoff
+      attributes = keyset_attributes_from(@records.last)
+      @options[:pre_serialize]&.(attributes)
+      attributes.values
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Offset
+    # Offset pagination without any COUNT query
+    class Countless < Offset
+      def initialize(**)
+        assign_options(**)
+        assign_and_check(limit: 1, page: 1)
+        @last = @options[:last] unless @options[:headless]
+        assign_offset
+      end
+
+      def records(collection)
+        return super if @options[:headless]
+
+        fetched = collection.offset(@offset).limit(@limit + 1).to_a # eager load limit + 1
+        finalize(fetched.size)                                      # finalize the pagy object
+        fetched[0, @limit]                                          # ignore the extra item
+      end
+
+      protected
+
+      def countless? = true
+
+      # Finalize the instance variables based on the fetched size
+      def finalize(fetched_size)
+        # empty records (trigger the right info message for known 0 count)
+        @count = 0 if fetched_size.zero? && @page == 1
+
+        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 = (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
+
+      prepend Deprecated::Countless if defined?(Deprecated::Countless)
+    end
+  end
+end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/abilities/shiftable'
+require_relative '../../modules/abilities/rangeable'
+
+class Pagy
+  # Implements Offset Pagination
+  class Offset < Pagy
+    DEFAULT = { page: 1 }.freeze
+
+    autoload :Countless, Pathname.new(__dir__).join('countless')
+    autoload :Countish,  Pathname.new(__dir__).join('countish')
+
+    include Rangeable
+    include Shiftable
+    include NumericHelpers
+
+    def initialize(**)
+      assign_options(**)
+      assign_and_check(limit: 1, count: 0, page: 1)
+      assign_last
+      assign_offset
+
+      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
+
+    attr_reader :offset, :count, :from, :to, :in, :previous, :next, :last
+    alias pages last
+
+    def records(collection)
+      collection.offset(@offset).limit(@limit)
+    end
+
+    protected
+
+    def offset? = true
+
+    def assign_last
+      @last = [(@count.to_f / @limit).ceil, 1].max
+    end
+
+    def assign_offset
+      @offset = (@limit * (@page - 1))
+    end
+
+    # Called by false in_range?
+    def assign_empty_page_variables
+      @in = @from = @to = 0     # options relative to the actual page
+      @previous = @last         # @previous relative to the actual page
+    end
+
+    prepend Deprecated::Offset if defined?(Deprecated::Offset)
+  end
+end

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

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+class Pagy
+  module Search
+    class Arguments < Array
+      def respond_to_missing?(*) = true
+
+      def method_missing(*) = push(*)
+    end
+
+    # Collect the search arguments to pass to the actual search
+    def pagy_search(*arguments, **options, &block)
+      Arguments.new([self, arguments, options, block])
+    end
+  end
+
+  # Search classes do not use OFFSET for querying a DB;
+  # however, they use the same positional technique used by Offset.
+  class SearchBase < Offset
+    DEFAULT = { search_method: :search }.freeze
+
+    def search? = true
+  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

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+class Pagy
+  # 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(options)
+      @options = options
+      request  = @options[:request]
+      @base_url, @path, @params, @cookie =
+        if request.is_a?(Hash)
+          request.values_at(:base_url, :path, :params, :cookie)
+        else
+          [request.base_url, request.path, get_params(request), request.cookies['pagy']]
+        end
+      freeze
+    end
+
+    attr_reader :base_url, :path, :params, :cookie
+
+    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 if page.is_a?(String) && !page.empty?
+    end
+
+    def resolve_limit
+      default   = @options[:limit] || DEFAULT[:limit]
+      max_limit = @options[: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
+
+    private
+
+    # Overriding support
+    def get_params(request)
+      request.GET.merge(request.POST).to_h.freeze
+    end
+
+    prepend Deprecated::Request if defined?(Deprecated::Request)
+  end
+end

data/lib/pagy/cli.rb

@@ -0,0 +1,122 @@
+# 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(19)}#{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)
+      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
+  end
+end

data/lib/pagy/console.rb

@@ -1,23 +1,8 @@
-# See Pagy::Console API documentation: https://ddnexus.github.io/pagy/docs/api/console
 # frozen_string_literal: true
 
-require 'pagy'  # so you can require just the extra in the console
-require 'pagy/extras/standalone'
+# Console loader
 
-class Pagy
-  # 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)
-      DEFAULT[:url] = 'http://www.example.com/subdir'
-    end
-
-    # Require the extras passed as arguments
-    def pagy_extras(*extras)
-      extras.each { |extra| require "pagy/extras/#{extra}" }
-      puts "Required extras: #{extras.map(&:inspect).join(', ')}"
-    end
-  end
-end
+# :nocov:
+require 'pagy'
+include Pagy::Console # rubocop:disable Style/MixinUsage
+# :nocov:

data/lib/pagy/deprecated.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# This file relegates all the deprecation warnings and code.
+# Pagy already implements the next code and this file works as a compatibility layer
+# to avoid breaking changes in the current version, respecting the Semantic Version contract.
+class Pagy
+  module Deprecated
+    def self.client_max_limit(options)
+      if (max_limit = options.delete(:client_max_limit))
+        options[:max_limit] ||= max_limit
+        warn '[PAGY] the :client_max_limit option is deprecated: use :max_limit instead.'
+      end
+    end
+
+    module Pagy
+      def assign_options(**options)
+        if options.key?(:max_pages)
+          warn '[PAGY] the :max_pages option is deprecated: ' \
+               'use https://ddnexus.github.io/pagy/guides/how-to/#paginate-only-max-records instead.'
+        end
+        Deprecated.client_max_limit(options) # if used without Request#resolve_limit
+        super
+      end
+    end
+
+    ##### Enabled from the autoloaded class #####
+
+    module Request  # :client_max_limit option
+      def resolve_limit
+        Deprecated.client_max_limit(@options)
+        super
+      end
+    end
+
+    module Offset
+      def assign_last
+        super
+        @last = @options[:max_pages] if @options[:max_pages] && @last > @options[:max_pages]
+      end
+    end
+
+    module Countless
+      def initialize(**)
+        super
+        @page = upto_max_pages(@page)
+        @last = upto_max_pages(@last) unless @options[:headless]
+      end
+
+      def finalize(fetched_size)
+        super
+        @last = upto_max_pages(@last)
+      end
+
+      def upto_max_pages(value)
+        return value unless value && @options[:max_pages]
+
+        [value, @options[:max_pages]].min
+      end
+    end
+
+    module Keynav
+      def next
+        records
+        super unless @options[:max_pages] && @page >= @options[:max_pages]
+      end
+    end
+  end
+
+  prepend Deprecated::Pagy
+
+  # Reopen the module and add the deprecated methods
+  module Configurable
+    def options
+      OPTIONS.tap do
+        warn "[PAGY] 'Pagy.options' is deprecated: use 'Pagy::OPTIONS directly'"
+      end
+    end
+
+    def sync_javascript(...)
+      warn "[PAGY] 'Pagy.sync_javascript(...)' is deprecated: use 'Pagy.sync(:javascript, ...)' instead."
+      sync(:javascript, ...)
+    end
+  end
+end

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

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Configuration methods
+  module Configurable
+    # Sync the pagy resource targets.
+    def sync(resource, destination, *targets)
+      files    = ROOT.join("#{resource}s").glob("{#{targets.join(',')}}")
+      unknownn = targets - files.map { |f| f.basename.to_s }
+      raise InternalError, "Resource not known: #{unknownn.join(', ')}" if unknownn.any?
+
+      FileUtils.cp(files, destination)
+    end
+
+    # Generate the script and style tags to help development
+    def dev_tools(wand_scale: 1)
+      <<~HTML
+        <script id="pagy-ai-widget">
+          #{ROOT.join('javascripts/ai_widget.js').read}
+        </script>
+        <script id="pagy-wand" data-scale="#{wand_scale}">
+          #{ROOT.join('javascripts/wand.js').read}
+        </script>
+        <style id="pagy-wand-default">
+          #{ROOT.join('stylesheets/pagy.css').read}
+        </style>
+      HTML
+    end
+
+    # Setup pagy for using the i18n gem
+    def translate_with_the_slower_i18n_gem!
+      send(:remove_const, :I18n)
+      send(:const_set, :I18n, ::I18n)
+      ::I18n.load_path += Dir[ROOT.join('locales/*.yml')]
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Count a collection
+  module Countable
+    module_function
+
+    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