pagy 9.4.0 → 43.5.5

data/lib/pagy/classes/calendar/calendar.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'active_support'
+require 'active_support/core_ext/time'
+require 'active_support/core_ext/date_and_time/calculations'
+require 'active_support/core_ext/numeric/time'
+require 'active_support/core_ext/integer/time'
+
+class Pagy
+  # Calendar class, subclass of Hash
+  class Calendar < Hash
+    path = Pathname.new(__dir__)
+    autoload :Unit,    path.join('unit')
+    autoload :Day,     path.join('day')
+    autoload :Week,    path.join('week')
+    autoload :Month,   path.join('month')
+    autoload :Quarter, path.join('quarter')
+    autoload :Year,    path.join('year')
+
+    # List of units in desc order of duration. It can be used for custom units.
+    UNITS = %i[year quarter month week day]  # rubocop:disable Style/MutableConstant
+
+    class << self
+      def localize_with_rails_i18n_gem(*locales)
+        Unit.prepend(Module.new { def localize(...) = ::I18n.localize(...) })
+        # :nocov:
+        raise RailsI18nLoadError, "Pagy: The gem 'rails-i18n' must be installed if you don't use Rails" \
+              unless (path = Gem.loaded_specs['rails-i18n']&.full_gem_path)
+
+        # :nocov:
+        path = Pathname.new(path)
+        ::I18n.load_path += locales.map { |locale| path.join("rails/locale/#{locale}.yml") }
+      end
+
+      private
+
+      # Return calendar, from, to
+      def init(...) = new.send(:init, ...)
+    end
+
+    # The current time of the smallest time unit shown
+    def showtime = self[@units.last].from
+
+    # The url for the calendar (shortest unit) page at time
+    def url_at(time, **)
+      page_keys = {}
+
+      @units.inject(nil) do |parent, unit|
+        unit_conf          = @conf[unit]
+        unit_conf[:period] = parent&.send(:active_period) || @period
+        unit_conf[:page]   = page = create(unit, **unit_conf).send(:page_at, time, **)
+
+        page_keys["#{unit}_#{@page_key}"] = page
+        unit_conf[:querify] = ->(params) { params.merge!(page_keys) }
+
+        create(unit, **unit_conf)
+      end.send(:compose_page_url, 1, **)
+    end
+
+    private
+
+    # Create the calendar
+    def init(conf, period, params)
+      @conf     = conf
+      @units    = Calendar::UNITS & conf.keys # get the units in time length desc order
+      @period   = period
+      @params   = params
+      @page_key = conf[:offset][:page_key] || DEFAULT[:page_key]
+
+      # Set all the :page_key options for later deletion
+      @units.each { |unit| conf[unit][:page_key] = "#{unit}_#{@page_key}" }
+
+      calendar    = {}
+      unit_object = nil
+
+      @units.each_with_index do |unit, index|
+        params_to_delete    = @units[(index + 1)..].map { conf[_1][:page_key] } + [@page_key]
+        unit_conf           = conf[unit]
+        unit_conf[:querify] = ->(up) { up.except!(*params_to_delete.map(&:to_s)) }
+        unit_conf[:period]  = unit_object&.send(:active_period) || @period
+        unit_conf[:page]    = @params[unit_conf[:page_key]] # requested page
+        # Simplecov doesn't need to cover a fail block_given?
+        # :nocov:
+        unit_conf[:counts] = yield(unit, unit_conf[:period]) if block_given?
+        # :nocov:
+        calendar[unit] = unit_object = create(unit, **unit_conf)
+      end
+
+      [replace(calendar), unit_object.from, unit_object.to]
+    end
+
+    # Create an instance of a Unit subclass by using its name (internal use)
+    def create(unit, **)
+      raise InternalError, "unit must be in #{UNITS.inspect}; got #{unit}" unless UNITS.include?(unit)
+
+      unit_class = Pagy::Calendar.const_get(unit.to_s.capitalize)
+
+      unit_class.new(**, request: @conf[:request])
+    end
+  end
+end

data/lib/pagy/{calendar → classes/calendar}/day.rb

@@ -1,19 +1,16 @@
-# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
 # frozen_string_literal: true
 
-class Pagy # :nodoc:
-  class Calendar # :nodoc:
-    # Day unit subclass
+class Pagy
+  class Calendar
     class Day < Unit
-      DEFAULT = { size:   31,   # rubocop:disable Style/MutableConstant
-                  ends: false,
-                  order:  :asc,
-                  format: '%d' }
+      DEFAULT = { slots:   31,
+                  compact: true,
+                  order:   :asc,
+                  format:  '%d' }.freeze
 
       protected
 
-      # Set up the calendar variables
-      def assign_unit_vars
+      def assign_unit_variables
         super
         @initial = @starting.beginning_of_day
         @final   = @ending.tomorrow.beginning_of_day
@@ -22,7 +19,6 @@ class Pagy # :nodoc:
         @to      = @from.tomorrow
       end
 
-      # Starting time for the page
       def starting_time_for(page)
         @initial.days_since(time_offset_for(page))
       end

data/lib/pagy/{calendar → classes/calendar}/month.rb

@@ -1,19 +1,16 @@
-# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
 # frozen_string_literal: true
 
 class Pagy # :nodoc:
   class Calendar # :nodoc:
-    # Month unit subclass
     class Month < Unit
-      DEFAULT = { size: 12,   # rubocop:disable Style/MutableConstant
-                  ends: false,
-                  order: :asc,
-                  format: '%b' }
+      DEFAULT = { slots:   12,
+                  compact: true,
+                  order:   :asc,
+                  format:  '%b' }.freeze
 
       protected
 
-      # Set up the calendar variables
-      def assign_unit_vars
+      def assign_unit_variables
         super
         @initial = @starting.beginning_of_month
         @final   = @ending.next_month.beginning_of_month
@@ -22,7 +19,6 @@ class Pagy # :nodoc:
         @to      = @from.next_month
       end
 
-      # Starting time for the page
       def starting_time_for(page)
         @initial.months_since(time_offset_for(page))
       end
@@ -33,7 +29,6 @@ class Pagy # :nodoc:
 
       private
 
-      # Number of months in time
       def months_in(time)
         (time.year * 12) + time.month
       end

data/lib/pagy/{calendar → classes/calendar}/quarter.rb

@@ -1,26 +1,23 @@
-# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
 # frozen_string_literal: true
 
 class Pagy # :nodoc:
   class Calendar # :nodoc:
-    # Quarter unit subclass
     class Quarter < Unit
-      DEFAULT = { size:   4,      # rubocop:disable Style/MutableConstant
-                  ends: false,
-                  order:  :asc,
-                  format: 'Q%q' } # '%q' token
+      DEFAULT = { slots:   4,
+                  compact: true,
+                  order:   :asc,
+                  format:  'Q%q' }.freeze # '%q' token
+
+      protected
 
       # The label for any page, with the substitution of the '%q' token
-      def label_for(page, opts = {})
+      def page_label(page, **options)
         starting_time = starting_time_for(page.to_i)  # page could be a string
-        opts[:format] = (opts[:format] || @vars[:format]).gsub('%q') { (starting_time.month / 3.0).ceil }
-        localize(starting_time, opts)
+        options[:format] = (options[:format] || @options[:format]).gsub('%q') { (starting_time.month / 3.0).ceil }
+        localize(starting_time, **options)
       end
 
-      protected
-
-      # Set up the calendar variables
-      def assign_unit_vars
+      def assign_unit_variables
         super
         @initial = @starting.beginning_of_quarter
         @final   = @ending.next_quarter.beginning_of_quarter
@@ -29,7 +26,6 @@ class Pagy # :nodoc:
         @to      = @from.next_quarter
       end
 
-      # Starting time for the page
       def starting_time_for(page)
         @initial.months_since(time_offset_for(page) * 3)
       end
@@ -40,7 +36,6 @@ class Pagy # :nodoc:
 
       private
 
-      # Number of months in time
       def months_in(time)
         (time.year * 12) + time.month
       end

data/lib/pagy/classes/calendar/unit.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../../modules/abilities/shiftable'
+require_relative '../../modules/abilities/rangeable'
+
+class Pagy
+  class Calendar
+    # Base class for time units subclasses (Year, Quarter, Month, Week, Day).
+    #
+    # To define a "bimester" unit you should:
+    # - Define a `Pagy::Calendar::Bimester` class.
+    # - Add the `:bimester` unit symbol in the `Pagy::Calendar::UNITS`.
+    # - Ensure the desc duration order of the UNITS (i.e. insert it between `:quarter` and `:month`).
+    class Unit < Pagy
+      DEFAULT = { page: 1 }.freeze
+
+      include Rangeable
+      include Shiftable
+      include NumericHelpers
+
+      def initialize(**)
+        assign_options(**)
+        assign_and_check(page: 1)
+        assign_unit_variables
+        unless in_range? { @page <= @last }
+          assign_empty_page_variables
+          return
+        end
+
+        assign_previous_and_next
+      end
+
+      attr_reader :order, :from, :to, :previous, :last
+      alias pages last
+
+      protected
+
+      def calendar? = true
+
+      # Called by false in_range?
+      def assign_empty_page_variables
+        @in = @from = @to = 0                        # options relative to the actual page
+        edge = @order == :asc ? @final : @initial    # get the edge of the range (neat, but any time would do)
+        @from = @to = edge                           # set both to the edge time (a >=&&< query will get no records)
+        @previous = @last
+      end
+
+      # The page that includes time.
+      # In case of time out of range, the :fit_time option avoids the RangeError
+      # and returns the closest page to the passed time argument (first or last page).
+      def page_at(time, **options)
+        fit_time  = time
+        fit_final = @final - 1
+        unless time.between?(@initial, fit_final)
+          raise RangeError.new(self, :time, "between #{@initial} and #{fit_final}", time) unless options[:fit_time]
+
+          fit_time = time < @final ? @initial : fit_final
+        end
+        offset = page_offset_at(fit_time)   # offset starts from 0
+        @order == :asc ? offset + 1 : @last - offset
+      end
+
+      # Base class method for the setup of the unit variables (subclasses must implement it and call super).
+      def assign_unit_variables
+        @order = @options[:order]
+        @starting, @ending = @options[:period]
+        raise OptionError.new(self, :period, 'to be an Array of min and max TimeWithZone instances', @options[:period]) \
+              unless @starting.is_a?(ActiveSupport::TimeWithZone) \
+                  && @ending.is_a?(ActiveSupport::TimeWithZone) && @starting <= @ending
+      end
+
+      # Apply the strftime format to the time.
+      # Localization other than :en, requires the rails-I18n gem.
+      def localize(time, **options)
+        # Impossible to "unprepend" the rails-i18n after it runs localize_with_rails_i18n_gem in test.
+        # :nocov:
+        time.strftime(options[:format])
+        # :nocov:
+      end
+
+      # The number of time units to offset from the @initial time, in order to get the ordered starting time for the page.
+      # Used in starting_time_for(page) where page starts from 1 (e.g. page to starting_time means subtracting 1).
+      def time_offset_for(page)
+        @order == :asc ? page - 1 : @last - page
+      end
+
+      # Period of the active page (used internally for nested units).
+      def active_period
+        [[@starting, @from].max, [@to - 1, @ending].min] # -1 sec: include only last unit day
+      end
+    end
+  end
+end

data/lib/pagy/{calendar → classes/calendar}/week.rb

@@ -1,17 +1,14 @@
-# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
 # frozen_string_literal: true
 
-class Pagy # :nodoc:
-  class Calendar # :nodoc:
-    # Week unit subclass
+class Pagy
+  class Calendar
     class Week < Unit
-      DEFAULT  = { order:  :asc,      # rubocop:disable Style/MutableConstant
-                   format: '%Y-%W' }
+      DEFAULT  = { order:  :asc,
+                   format: '%Y-%W' }.freeze
 
       protected
 
-      # Set up the calendar variables
-      def assign_unit_vars
+      def assign_unit_variables
         super
         @initial = @starting.beginning_of_week
         @final   = @ending.next_week.beginning_of_week
@@ -20,7 +17,6 @@ class Pagy # :nodoc:
         @to      = @from.next_week
       end
 
-      # Starting time for the page
       def starting_time_for(page)
         @initial.weeks_since(time_offset_for(page))
       end

data/lib/pagy/{calendar → classes/calendar}/year.rb

@@ -1,19 +1,18 @@
-# See Pagy::Countless API documentation: https://ddnexus.github.io/pagy/docs/api/calendar
 # frozen_string_literal: true
 
 class Pagy # :nodoc:
   class Calendar # :nodoc:
     # Year unit subclass
     class Year < Unit
-      DEFAULT = { size:   10,   # rubocop:disable Style/MutableConstant
-                  ends: false,
-                  order:  :asc,
-                  format: '%Y' }
+      DEFAULT = { slots:   10,
+                  compact: true,
+                  order:   :asc,
+                  format:  '%Y' }.freeze
 
       protected
 
       # Set up the calendar variables
-      def assign_unit_vars
+      def assign_unit_variables
         super
         @initial = @starting.beginning_of_year
         @final   = @ending.next_year.beginning_of_year

data/lib/pagy/classes/exceptions.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Specific subclass of ArgumentError
+  class OptionError < ArgumentError
+    attr_reader :pagy, :option, :value
+
+    # Prepare a useful feedback
+    def initialize(pagy, option, description, value)
+      @pagy   = pagy
+      @option = option
+      @value  = value
+
+      super("expected :#{@option} #{description}; got #{@value.inspect}")
+    end
+  end
+
+  # Specific subclass of OptionError
+  class RangeError < OptionError; end
+
+  # I18n localization error
+  class RailsI18nLoadError < LoadError; end
+
+  # Generic internal error
+  class InternalError < StandardError; end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Keyset
+    module Adapters
+      # Keyset adapter for ActiveRecord
+      module ActiveRecord
+        def extract_keyset
+          @set.order_values.each_with_object({}) do |node, keyset|
+            keyset[node.value.name.to_sym] ||= node.direction
+          end
+        end
+
+        def keyset_attributes_from(record)
+          record.slice(*@keyset.keys)
+        end
+
+        def quoted_identifiers(table)
+          connection = @set.connection
+          @keyset.to_h { |column| [column, "#{connection.quote_table_name(table)}.#{connection.quote_column_name(column)}"] }
+        end
+
+        def typecast(attributes)
+          model = @set.model
+          {}.tap do |result|
+            @keyset.each_key do |k|
+              result[k] = model.type_for_attribute(k).cast(attributes[k])
+            end
+          end
+        end
+
+        def ensure_select
+          return if @set.select_values.empty?
+
+          @set = @set.select(*@keyset.keys)
+        end
+
+        def apply_where(predicate, arguments)
+          @set = @set.where(predicate, **arguments)
+        end
+
+        def self.included(including)
+          instance_methods(false).each do |method_name|
+            including.send(:protected, method_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Keyset
+    module Adapters
+      # Keyset adapter for Sequel ORM
+      module Sequel
+        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
+
+        def keyset_attributes_from(record)
+          record.to_hash.slice(*@keyset.keys)
+        end
+
+        def quoted_identifiers(table)
+          db = @set.db
+          @keyset.to_h { |column| [column, "#{db.quote_identifier(table)}.#{db.quote_identifier(column)}"] }
+        end
+
+        def typecast(attributes)
+          model = @set.model
+          db    = @set.db
+          {}.tap do |result|
+            @keyset.each_key do |k|
+              type      = model.db_schema[k].fetch(:type)
+              result[k] = db.typecast_value(type, attributes[k])
+            end
+          end
+        end
+
+        def ensure_select
+          return if @set.opts[:select].nil?
+
+          selected = @set.opts[:select]
+          @set = @set.select_append(*@keyset.keys.reject { |c| selected.include?(c) })
+        end
+
+        def apply_where(predicate, arguments)
+          @set = @set.where(::Sequel.lit(predicate, **arguments))
+        end
+
+        def self.included(including)
+          instance_methods(false).each do |method_name|
+            including.send(:protected, method_name)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Keyset
+    # Keyset pagination with broad UI support
+    class Keynav < Keyset
+      # Avoid conflicts between filter arguments in composite SQL fragments
+      PRIOR_PREFIX = 'prior_'
+      PAGE_PREFIX  = 'page_'
+
+      # Define empty subclasses to allow specific typing without triggering autoload
+      class ActiveRecord < self; end
+      class Sequel < self; end
+
+      include NumericHelpers
+
+      # Finalize the instance variables needed for the UI
+      def initialize(set, **)
+        super
+
+        @previous = @page - 1 unless @page == 1
+        @in       = @records.size
+      end
+
+      attr_reader :update, :previous, :last
+      alias pages last
+
+      # Prepare the @update for the client when it's a new page, and return the next page number
+      def next
+        records
+        @count = 0 if !@more && @page == 1  # empty records (trigger the right info message for known 0 count)
+        return unless @more
+
+        @next ||= begin
+                    unless @page_cutoff
+                      @page_cutoff = extract_cutoff
+                      @last       += 1                                # reflect the added cutoff
+                      @update.push(@last, [@page, 1, @page_cutoff])   # last + splice arguments for the client cutoffs
+                    end
+                    @page + 1
+                  end
+      end
+
+      protected
+
+      def keynav? = true
+
+      # Process the page array
+      def assign_page
+        if @options[:page]
+          storage_key, @page, @last, @prior_cutoff, @page_cutoff = @options[:page]
+        else
+          @page = @last = 1
+        end
+
+        @update = [storage_key, @options[:root_key], @options[:page_key]]
+      end
+
+      # Use a compound predicate to fetch the records
+      def fetch_records
+        return super unless @page_cutoff # last page
+
+        # Compound predicate for visited pages
+        predicate = +''
+        arguments = {}
+
+        if @prior_cutoff # not the first page
+          # Include the records after @prior_cutoff
+          predicate << "(#{compose_predicate(PRIOR_PREFIX)}) AND "
+          arguments.merge!(arguments_from(@prior_cutoff, PRIOR_PREFIX))
+        end
+
+        # Exclude the records after @page_cutoff
+        predicate << "NOT (#{compose_predicate(PAGE_PREFIX)})"
+        arguments.merge!(arguments_from(@page_cutoff, PAGE_PREFIX))
+        apply_where(predicate, arguments)
+
+        @more = true          # not the last page
+        @set.limit(nil).to_a  # replaced by the compound predicate
+      end
+
+      prepend Deprecated::Keynav if defined?(Deprecated::Keynav)
+    end
+  end
+end