pagy 9.3.5 → 43.0.0.rc2

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

@@ -0,0 +1,98 @@
+# 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
+  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
+      # :nocov:
+      # Localize with rails-i18n in any env
+      def localize_with_rails_i18n_gem(*locales)
+        Unit.prepend(Module.new { def localize(...) = ::I18n.localize(...) })
+        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)
+
+        path = Pathname.new(path)
+        ::I18n.load_path += locales.map { |locale| path.join("rails/locale/#{locale}.yml") }
+      end
+      # :nocov:
+
+      private
+
+      # Return calendar, from, to
+      def init(...)
+        new.send(:init, ...)
+      end
+    end
+
+    # Return the current time of the smallest time unit shown
+    def showtime
+      self[@units.last].from
+    end
+
+    # Return the url for the calendar (shortest unit) page at time
+    def url_at(time, **)
+      conf      = Marshal.load(Marshal.dump(@conf))
+      page_keys = {}
+      @units.inject(nil) do |object, unit|
+        conf[unit][:period]  = object&.send(:active_period) || @period
+        conf[unit][:page]    = page_keys["#{unit}_#{@page_key}"] \
+                             = create(unit, **conf[unit]).send(:page_at, time, **)
+        conf[unit][:querify] = ->(query) { query.merge!(page_keys) }
+        create(unit, **conf[unit])
+      end.send(:compose_page_url, 1, **)
+    end
+
+    private
+
+    # Create the calendar
+    def init(conf, period, query)
+      @conf     = Marshal.load(Marshal.dump(conf))  # store a copy
+      @units    = Calendar::UNITS & @conf.keys # get the units in time length desc order
+      @period   = period
+      @query    = query
+      @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 = {}
+      object   = nil
+      @units.each_with_index do |unit, index|
+        params_to_delete     = @units[(index + 1), @units.length].map { |sub| conf[sub][:page_key] } + [@page_key]
+        conf[unit][:querify] = ->(up) { up.except!(*params_to_delete.map(&:to_s)) }
+        conf[unit][:period]  = object&.send(:active_period) || @period
+        conf[unit][:page]    = @query["#{unit}_#{@page_key}"] # requested page
+        # :nocov:
+        # simplecov doesn't need to fail block_given?
+        conf[unit][:counts] = yield(unit, conf[unit][:period]) if block_given?
+        # :nocov:
+        calendar[unit] = object = create(unit, **conf[unit])
+      end
+      [replace(calendar), object.from, object.to]
+    end
+
+    # Create a unit subclass instance by using the unit name (internal use)
+    def create(unit, **)
+      raise InternalError, "unit must be in #{UNITS.inspect}; got #{unit}" unless UNITS.include?(unit)
+
+      name    = +unit.to_s
+      name[0] = name[0].capitalize
+      Pagy::Calendar.const_get(name).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,92 @@
+# 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 durtion order of the UNITS (i.e. insert it between `:quarter` and `:month`)
+    class Unit < Pagy
+      DEFAULT = { page: 1 }.freeze
+
+      include Rangeable
+      include Shiftable
+
+      def initialize(**)    # rubocop:disable Lint/MissingSuper
+        assign_options(**)
+        assign_and_check(page: 1)
+        assign_unit_variables
+        return unless in_range? { @page <= @last }
+
+        assign_previous_and_next
+      end
+
+      attr_reader :order, :from, :to, :previous, :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]
+
+          if time < @final
+            fit_time = @initial
+            ordinal  = 'first'
+          else
+            fit_time = fit_final
+            ordinal  = 'last'
+          end
+          warn "Pagy::Calendar#page_at: Rescued #{time} out of range by returning the #{ordinal} page."
+        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 a 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, require the rails-I18n gem.
+      def localize(time, **options)
+        time.strftime(options[:format])
+      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,33 @@
+# frozen_string_literal: true
+
+class Pagy
+  # Generic option error
+  class OptionError < ArgumentError
+    attr_reader :pagy, :option, :value
+
+    # Set the options and prepare the message
+    def initialize(pagy, option, description, value)
+      @pagy   = pagy
+      @option = option
+      @value  = value
+      super("expected :#{@option} #{description}; got #{@value.inspect}")
+    end
+  end
+
+  # Specific range error
+  class RangeError < OptionError; end
+
+  # I18n localization error
+  class RailsI18nLoadError < LoadError; end
+
+  # Generic internal error
+  class InternalError < StandardError; end
+
+  # JsonApi :page param error
+  class JsonapiReservedParamError < StandardError
+    # Inform about the actual value
+    def initialize(value)
+      super("expected reserved :page param to be nil or Hash-like; got #{value.inspect}")
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require_relative 'adapters/active_record'
+
+class Pagy
+  class Keyset
+    class ActiveRecord < Keyset
+      include Adapters::ActiveRecord
+    end
+  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
+        # 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
+
+        # Get the keyset attributes from a record
+        def keyset_attributes_from(record) = record.slice(*@keyset.keys)
+
+        # Get the hash of quoted keyset identifiers
+        def quoted_identifiers(table)
+          connection = @set.connection
+          @keyset.to_h { |column| [column, "#{connection.quote_table_name(table)}.#{connection.quote_column_name(column)}"] }
+        end
+
+        # Typecast the attributes
+        def typecast(attributes)
+          @set.model.new(attributes).slice(attributes.keys)
+              .to_hash.transform_keys(&:to_sym)
+        end
+
+        # Append the missing keyset keys, if the set is restricted by select
+        def ensure_select
+          return if @set.select_values.empty?
+
+          @set = @set.select(*@keyset.keys)
+        end
+
+        # Apply the where predicate to the set
+        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,63 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Keyset
+    module Adapters
+      # Keyset adapter for sequel
+      module Sequel
+        # 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
+
+        # Get the keyset attributes from a record
+        def keyset_attributes_from(record) = record.to_hash.slice(*@keyset.keys)
+
+        # Get the hash of quoted keyset identifiers
+        def quoted_identifiers(table)
+          db = @set.db
+          @keyset.to_h { |column| [column, "#{db.quote_identifier(table)}.#{db.quote_identifier(column)}"] }
+        end
+
+        # Typecast the attributes
+        def typecast(attributes)
+          model = @set.opts[:model]
+          model.unrestrict_primary_key if (primary_key_is_restricted = model.restrict_primary_key?)
+          attributes = model.new(attributes).to_hash.slice(*attributes.keys.map(&:to_sym))
+          model.restrict_primary_key if primary_key_is_restricted
+          attributes
+        end
+
+        # Append the missing keyset keys, if the set is restricted by select
+        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
+
+        # Apply the where predicate to the set
+        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/active_record.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative '../adapters/active_record'
+
+class Pagy
+  class Keyset
+    class Keynav
+      class ActiveRecord < Keynav
+        include Adapters::ActiveRecord
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require_relative '../adapters/sequel'
+
+class Pagy
+  class Keyset
+    class Keynav
+      class Sequel < Keynav
+        include Adapters::Sequel
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+class Pagy
+  class Keyset
+    # Use keyset pagination with resources for all the frontend helpers
+    class Keynav < Keyset
+      # Avoid conflicts between filter arguments in composite SQL fragments
+      PRIOR_PREFIX = 'prior_'
+      PAGE_PREFIX  = 'page_'
+
+      path = Pathname.new(__FILE__).sub_ext('')
+      autoload :ActiveRecord, path.join('active_record')
+      autoload :Sequel,       path.join('sequel')
+
+      # Finalize the instance variables needed for the UI
+      def initialize(set, **)
+        super
+        # Ensure next is called, so the last page used by the UI helpers is known
+        self.next
+        @previous = @page - 1 unless @page == 1
+        @in       = @records.size
+      end
+
+      attr_reader :update, :previous, :last
+
+      # Prepare the @update for the client when it's a new page, and return the next page number
+      def next
+        records
+        return if !@more || (@options[:max_pages] && @page >= @options[:max_pages])
+
+        @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[: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
+    end
+  end
+end