Merge branch 'dev'

.github/ISSUE_TEMPLATE/Code.yml

@@ -19,7 +19,7 @@ body:
     attributes:
       label: 👀 Before submitting...
       options:
-        - label: I upgraded to pagy version 9.2.2
+        - label: I upgraded to pagy version 9.3.0
           required: true
         - label: I searched through the [Documentation](https://ddnexus.github.io/pagy/)
           required: true

.github/latest_release_body.md

@@ -6,12 +6,11 @@
 - See the [Changelog](https://ddnexus.github.io/pagy/changelog) for possible breaking changes
 <!-- whats_new_end -->
 
-### Changes in 9.2.2
+### Changes in 9.3.0
 
 <!-- changes_start -->
-- Replace inline templates with template block in sinatra apps
-- Replace the rails calendar app with a sinatra app
-- Add PagyApps::INDEX
+- Remove the :typecast_latest variable
+- Add the :jsonify_keyset_attributes variable to override the encoding (#749)
 <!-- changes_end -->
 
 [CHANGELOG](https://ddnexus.github.io/pagy/changelog)

.rubocop.yml

@@ -22,6 +22,9 @@ Layout/LineLength:
   Exclude:
   - test/**/*
 
+Layout/BeginEndAlignment:
+  EnforcedStyleAlignWith: begin
+
 Layout/ExtraSpacing:
   AllowForAlignment:
     Enabled: true

CHANGELOG.md

@@ -23,6 +23,11 @@ If you upgrade from version `< 9.0.0` see the following:
 - `:after_latest` keyset variable: use `:filter_newest`
 <hr>
 
+## Version 9.3.0
+
+- Remove the :typecast_latest variable
+- Add the :jsonify_keyset_attributes variable to override the encoding (#749)
+
 ## Version 9.2.2
 
 - Replace inline templates with template block in sinatra apps

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: gem
   specs:
-    pagy (9.2.2)
+    pagy (9.3.0)
 
 GEM
   remote: https://rubygems.org/
@@ -125,7 +125,7 @@ GEM
     irb (1.14.1)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.8.1)
+    json (2.8.2)
     language_server-protocol (3.17.0.3)
     listen (3.9.0)
       rb-fsevent (~> 0.10, >= 0.10.3)
@@ -197,7 +197,7 @@ GEM
       rack (>= 3.0.0)
     rack-test (2.1.0)
       rack (>= 1.3)
-    rackup (2.2.0)
+    rackup (2.2.1)
       rack (>= 3)
     rails (8.0.0)
       actioncable (= 8.0.0)
@@ -241,7 +241,7 @@ GEM
     rematch (3.1.0)
     rerun (0.14.0)
       listen (~> 3.0)
-    rouge (4.5.0)
+    rouge (4.5.1)
     rubocop (1.68.0)
       json (~> 2.3)
       language_server-protocol (>= 3.17.0)
@@ -252,14 +252,14 @@ GEM
       rubocop-ast (>= 1.32.2, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.34.1)
+    rubocop-ast (1.36.1)
       parser (>= 3.3.1.0)
     rubocop-minitest (0.36.0)
       rubocop (>= 1.61, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-packaging (0.5.2)
       rubocop (>= 1.33, < 2.0)
-    rubocop-performance (1.22.1)
+    rubocop-performance (1.23.0)
       rubocop (>= 1.48.1, < 2.0)
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-rake (0.6.0)
@@ -298,7 +298,7 @@ GEM
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.6.0)
-    uri (1.0.1)
+    uri (1.0.2)
     useragent (0.16.10)
     websocket-driver (0.7.6)
       websocket-extensions (>= 0.1.0)

docs/api/keyset.md

@@ -114,7 +114,7 @@ If you need a specific order:
 ### How Pagy::Keyset works
 
 - You pass an `uniquely ordered` `set` and `Pagy::Keyset` queries the page of records.
-- It keeps track of the `latest` fetched  record by encoding its `keyset` attributes into the `page` query string param of the 
+- It keeps track of the `latest` fetched record by encoding its `keyset` attributes into the `page` query string param of the 
   `next` URL.
 - At each request, the `:page` is decoded and used to prepare a `when` clause that filters the newest records, and 
   the `:limit` of records is pulled.
@@ -181,21 +181,37 @@ end
 Pagy::Keyset(set, filter_newest:)
 ```
 
-==- `:typecast_latest`
+==- `:jsonify_keyset_attributes`
 
-A lambda to override the automatic typecasting of your ORM. For example: `SQLite` stores date and times as strings, and
-the query interpolation may fail composing and comparing string dates. The `typecast_latest` is an effective last-resort
-option when fixing the typecasting in your models and/or the data in your storage is not possible.
+A lambda to override the generic json encoding of the `keyset` attributes. Use it when the generic `to_json` method would lose 
+some information when decoded.
+
+For example: `Time` objects may lose or round the fractional seconds through the 
+encoding/decoding cycle, causing the ordering to fail and thus creating all sort of unexpected behaviors (e.g. skipping or 
+repeating the same page, missing or duplicated records, etc.). Here is what you can do:
 
 ```ruby
-typecast_latest = lambda do |latest| 
-  latest[:timestamp] = Time.parse(latest[:timestamp]).strftime('%F %T')
-  latest
+# Match the microsecods with the strings stored into the time columns of SQLite
+jsonify_keyset_attributes = lambda do |attributes|
+  # Convert it to a string matching the stored value/format in SQLite DB
+  attributes[:created_at] = attributes[:created_at].strftime('%F %T.%6N')
+  attributes.to_json
 end
 
-Pagy::Keyset(set, typecast_latest:)
+Pagy::Keyset(set, jsonify_keyset_attributes:)
 ```
 
+!!! ActiveRecord alternative for time_precision
+
+With `ActiveRecord::Relation` set, you can fix the fractional seconds issue by just setting the `time_precision`: 
+
+```ruby
+ActiveSupport::JSON::Encoding.time_precision = 6
+```
+!!!
+
+_(Notice that it doesn't work with `Sequel::Dataset` sets)_
+
 ===
 
 ## Attribute Readers
@@ -206,7 +222,7 @@ Pagy::Keyset(set, typecast_latest:)
 
 ==- Records may repeat or be missing from successive pages
 
-!!!danger Your set is not `uniquely ordered`
+!!!danger The set may not be `uniquely ordered`
 
 ```rb
 # Neither columns are unique
@@ -221,20 +237,18 @@ Product.order(:name, :production_date, :id)
 ```
 !!!
 
-!!!danger ... or you have a typecasting problem
-Your ORM and the storage formats don't match for one or more columns. It's a common case with `SQLite` and Time columns.
-They may have been stored as strings formatted differently than the default format used by your current ORM.
+!!!danger You may have an encoding problem
+The generic `to_json` method used to encode the `page` may lose some information when decoded
 
 !!!success
 - Check the actual executed DB query and the actual stored value
 - Identify the column that have a format that doesn't match with the keyset
-- Fix the typecasting consistence of your ORM with your DB or consider using your custom typecasting with the 
-  [:typecast_latest](#typecast-latest) variable
+- Override the encoding with the [:jsonify_keyset_attributes](#jsonify-keyset-attributes) variable
 !!!
-  
+
 ==- The order is OK, but the DB is still slow
 
-!!!danger Most likely your index is not right, or your case needs a custom query
+!!!danger Most likely the index is not right, or your case needs a custom query
 
 !!! Success
 

gem/apps/calendar.ru

@@ -16,7 +16,7 @@
 # URL
 #    http://0.0.0.0:8000
 
-VERSION = '9.2.2'
+VERSION = '9.3.0'
 
 # Bundle
 require 'bundler/inline'

gem/apps/demo.ru

@@ -19,7 +19,7 @@
 # URL
 #    http://0.0.0.0:8000
 
-VERSION = '9.2.2'
+VERSION = '9.3.0'
 
 # Bundle
 require 'bundler/inline'

gem/apps/keyset_ar.ru

@@ -16,7 +16,7 @@
 # URL
 #    http://0.0.0.0:8000
 
-VERSION = '9.2.2'
+VERSION = '9.3.0'
 
 # Bundle
 require 'bundler/inline'
@@ -138,6 +138,10 @@ end
 
 # ActiveRecord setup
 require 'active_record'
+
+# Match the microsecods with the strings stored into the time columns of SQLite
+# ActiveSupport::JSON::Encoding.time_precision = 6
+
 # Log
 output = ENV['APP_ENV'].equal?('showcase') ? IO::NULL : $stdout
 ActiveRecord::Base.logger = Logger.new(output)

gem/apps/keyset_s.ru

@@ -16,7 +16,7 @@
 # URL
 #    http://0.0.0.0:8000
 
-VERSION = '9.2.2'
+VERSION = '9.3.0'
 
 # Bundle
 require 'bundler/inline'

gem/apps/rails.ru

@@ -16,7 +16,7 @@
 # URL
 #    http://0.0.0.0:8000
 
-VERSION = '9.2.2'
+VERSION = '9.3.0'
 
 # Gemfile
 require 'bundler/inline'

gem/apps/repro.ru

@@ -16,7 +16,7 @@
 # URL
 #    http://0.0.0.0:8000
 
-VERSION = '9.2.2'
+VERSION = '9.3.0'
 
 # Bundle
 require 'bundler/inline'

gem/bin/pagy

@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-VERSION = '9.2.2'
+VERSION = '9.3.0'
 LINUX   = RbConfig::CONFIG['host_os'].include?('linux')
 HOST    = '0.0.0.0'
 PORT    = '8000'

gem/config/pagy.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Pagy initializer file (9.2.2)
+# Pagy initializer file (9.3.0)
 # Customize only what you really need and notice that the core Pagy works also without any of the following lines.
 # Should you just cherry pick part of this file, please maintain the require-order of the extras