pagy 9.4.0 → 43.2.0

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

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require 'json'
+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')
+
+    class TypeError < ::TypeError; end
+
+    # Initialize Keyset* and Keyset::Keynav* classes and subclasses
+    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, **) }
+      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, **)
+    end
+
+    def initialize(set, **) # rubocop:disable Lint/MissingSuper
+      assign_options(**)
+      assign_and_check(limit: 1)
+      @set    = set
+      @keyset = @options[:keyset] || extract_keyset
+      raise InternalError, 'the set must be ordered' if @keyset.empty?
+
+      assign_page
+      self.next
+    end
+
+    # Return the array of records for the current page
+    def records
+      @records ||= begin
+                     ensure_select
+                     fetch_records
+                   end
+    end
+
+    # Return 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  = quoted_identifiers(@set.model.table_name)
+      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 ')
+      end
+    end
+
+    # Return 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
+
+    # Extract the cutoff from the last record (only called if @more)
+    def extract_cutoff
+      attributes = keyset_attributes_from(@records.last)
+      @options[:pre_serialize]&.(attributes)
+      attributes.values
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'adapters/sequel'
+
+class Pagy
+  class Keyset
+    class Sequel < Keyset
+      include Adapters::Sequel
+    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,61 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Offset
+    # Offset pagination without a count
+    class Countless < Offset
+      def initialize(**) # rubocop:disable Lint/MissingSuper
+        assign_options(**)
+        assign_and_check(limit: 1, page: 1)
+        @page = upto_max_pages(@page)
+        @last = upto_max_pages(@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
+
+      def upto_max_pages(value)
+        return value unless value && @options[:max_pages]
+
+        [value, @options[:max_pages]].min
+      end
+
+      # 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
+        return self unless in_range? { fetched_size.positive? || @page == 1 }
+
+        past  = @last && @page < @last # this page has been past
+        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

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

@@ -0,0 +1,56 @@
+# 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
+
+    def initialize(**) # rubocop:disable Lint/MissingSuper
+      assign_options(**)
+      assign_and_check(limit: 1, count: 0, page: 1)
+      assign_last
+      assign_offset
+      return unless in_range? { @page <= @last }
+
+      @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, :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
+      @last = @options[:max_pages] if @options[:max_pages] && @last > @options[:max_pages]
+    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
+  end
+end

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

@@ -0,0 +1,32 @@
+# 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(term = nil, **options, &block)
+      Arguments.new([self, term, 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
+end

data/lib/pagy/classes/request.rb

@@ -0,0 +1,36 @@
+# 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, request.GET.merge(request.POST).to_h, request.cookies['pagy']]
+        end
+    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]
+      page     = nil if page == ''   # fix for app-generated queries like ?page=
+      force_integer ? (page || 1).to_i : page
+    end
+
+    def resolve_limit
+      limit_key = @options[:limit_key] || DEFAULT[:limit_key]
+      return @options[:limit] || DEFAULT[:limit] \
+             unless @options[:client_max_limit] &&
+                    (requested_limit = @params.dig(@options[:root_key], limit_key) || @params[limit_key])
+
+      [requested_limit.to_i, @options[:client_max_limit]].min
+    end
+  end
+end

data/lib/pagy/console.rb

@@ -1,23 +1,6 @@
-# See Pagy::Console API documentation: https://ddnexus.github.io/pagy/docs/api/console
 # frozen_string_literal: true
 
-require_relative '../pagy'  # so you can require just the extra in the console
-require_relative '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
+require 'pagy'
+include Pagy::Console # rubocop:disable Style/MixinUsage

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

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Add configurstion methods
+  module Configurable
+    # Sync the pagy javascript targets
+    def sync_javascript(destination, *targets)
+      names   = %w[pagy.mjs pagy.js pagy.js.map pagy.min.js]
+      targets = names if targets.empty?
+      targets.each { |filename| FileUtils.cp(ROOT.join('javascripts', filename), destination) }
+      (names - targets).each { |filename| FileUtils.rm_f(File.join(destination, filename)) }
+    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
+  # 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

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+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
+      # Allow unescaped Pagy::RawQueryValue
+      def build_nested_query(value, prefix = nil)
+        case value
+        when Array
+          value.map { |v| build_nested_query(v, "#{prefix}[]") }.join('&')
+        when Hash
+          value.map do |k, v|
+            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?
+
+          escaped_value = value.is_a?(EscapedValue) ? value : escape(value)
+          "#{escape(prefix)}=#{escaped_value}"
+        end
+      end
+
+      def escape(str)
+        URI.encode_www_form_component(str)
+      end
+    end
+
+    protected
+
+    # Overriddable 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, **options)
+      root_key, page_key, limit_key, client_max_limit, limit, querify, absolute, path, fragment =
+        @options.merge(options)
+                .values_at(:root_key, :page_key, :limit_key, :client_max_limit, :limit, :querify, :absolute, :path, :fragment)
+      params = @request.params.clone(freeze: false)
+      (root_key ? params[root_key] ||= {} : params).tap do |h|
+        { page_key  => compose_page_param(page),
+          limit_key => client_max_limit && limit }.each { |k, v| v ? h[k] = v : h.delete(k) }
+      end
+      querify&.(params) # Must modify the params: the returned value is ignored
+      query_string = QueryUtils.build_nested_query(params).sub(/\A(?=.)/, '?')
+      fragment   &&= "##{fragment.delete_prefix('#')}"
+      "#{@request.base_url if absolute}#{path || @request.path}#{query_string}#{fragment}"
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Add method supporting range checking, range error and rescue
+  module Rangeable
+    # Check if in range
+    def in_range?
+      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
+      @in_range = false
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+class Pagy
+  module Shiftable
+    protected
+
+    def assign_previous_and_next
+      @previous = @page - 1 unless @page == 1
+      @next     = @page + 1 unless @page == @last
+    end
+  end
+end

data/lib/pagy/{b64.rb → modules/b64.rb}

@@ -1,17 +1,13 @@
 # frozen_string_literal: true
 
-class Pagy # :nodoc:
+class Pagy
   # Cheap Base64 specialized methods to avoid dependencies
   module B64
     module_function
 
-    def encode(bin)
-      [bin].pack('m0')
-    end
+    def encode(bin) = [bin].pack('m0')
 
-    def decode(str)
-      str.unpack1('m0')
-    end
+    def decode(str) = str.unpack1('m0')
 
     def urlsafe_encode(bin)
       str = encode(bin)

data/lib/pagy/modules/console.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Provide a ready to use pagy environment when included in irb/rails console
+  module Console
+    class Collection < Array
+      def initialize(arr = Array(1..1000))
+        super
+        @collection = clone
+      end
+
+      def offset(value) = tap { @collection = self[value..] }
+      def limit(value)  = @collection[0, value]
+      def count(*)      = size
+    end
+
+    include Method
+
+    # Direct reference to request.params via a method
+    def request    = @request ||= { base_url: 'http://www.example.com', path: '/path', params: { example: '123' } }
+    def params     = request[:params]
+    def collection = Collection
+  end
+end

data/lib/pagy/modules/i18n/i18n.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require_relative 'p11n'
+
+class Pagy
+  # Pagy i18n implementation, compatible with the I18n gem, just a lot faster and lighter
+  module I18n
+    extend self
+
+    def pathnames = @pathnames ||= [ROOT.join('locales')]
+    def locales   = @locales   ||= {}
+
+    # Store the variable for the duration of a single request
+    def locale=(value)
+      Thread.current[:pagy_locale] = value
+    end
+
+    def locale = Thread.current[:pagy_locale] || 'en'
+
+    # Translate and pluralize the key with the locale entries
+    def translate(key, **options)
+      data, p11n  = locales[locale] || self.load
+      translation = data[key] || (options[:count] && data[key += ".#{p11n.plural_for(options[:count])}"]) \
+                      or return %([translation missing: "#{key}"])
+      translation.gsub(/%{[^}]+?}/) { |match| options[:"#{match[2..-2]}"] || match }
+    end
+
+    private
+
+    def load
+      path = pathnames.reverse.map { |p| p.join("#{locale}.yml") }.find(&:exist?)
+      raise Errno::ENOENT, "missing dictionary file for #{locale.inspect} locale" unless path
+
+      dictionary      = YAML.load_file(path)[locale]
+      p11n            = dictionary['pagy'].delete('p11n')
+      locales[locale] = [flatten_to_dot_keys(dictionary), Object.const_get("Pagy::I18n::P11n::#{p11n}")]
+    end
+
+    # Create a flat hash with dotted notation keys
+    # e.g. { 'a' => { 'b' => {'c' => 3, 'd' => 4 }}} -> { 'a.b.c' => 3, 'a.b.d' => 4 }
+    def flatten_to_dot_keys(initial, prefix = '')
+      initial.reduce({}) do |hash, (key, value)|
+        hash.merge!(value.is_a?(Hash) ? flatten_to_dot_keys(value, "#{prefix}#{key}.") : { "#{prefix}#{key}" => value })
+      end
+    end
+  end
+end

data/lib/pagy/modules/i18n/p11n/arabic.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class Pagy
+  module I18n
+    module P11n
+      module Arabic
+        module_function
+
+        def plural_for(n = 0)
+          mod100 = n % 100
+          case
+          when n == 0  # rubocop:disable Style/NumericPredicate
+            :zero
+          when n == 1
+            :one
+          when n == 2
+            :two
+          when (3..10).to_a.include?(mod100)
+            :few
+          when (11..99).to_a.include?(mod100)
+            :many
+          else
+            :other
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pagy/modules/i18n/p11n/east_slavic.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Pagy
+  module I18n
+    module P11n
+      module EastSlavic
+        module_function
+
+        def plural_for(n = 0)
+          mod10  = n % 10
+          mod100 = n % 100
+          case
+          when mod10 == 1 && mod100 != 11
+            :one
+          when (2..4).to_a.include?(mod10) && !(12..14).to_a.include?(mod100)
+            :few
+          when mod10 == 0 || (5..9).to_a.include?(mod10) || (11..14).to_a.include?(mod100) # rubocop:disable Style/NumericPredicate
+            :many
+          else
+            :other
+          end
+        end
+      end
+    end
+  end
+end