Merge branch 'dev'

ddnexus · Nov 6, 2024 · f4b67d6 · f4b67d6
2 parents 3de9224 + f080628
commit f4b67d6
Show file tree

Hide file tree

Showing 25 changed files with 73 additions and 57 deletions.
diff --git a/.github/ISSUE_TEMPLATE/Code.yml b/.github/ISSUE_TEMPLATE/Code.yml
@@ -19,7 +19,7 @@ body:
     attributes:
       label: 👀 Before submitting...
       options:
-        - label: I upgraded to pagy version 9.1.1
+        - label: I upgraded to pagy version 9.2.0
           required: true
         - label: I searched through the [Documentation](https://ddnexus.github.io/pagy/)
           required: true

diff --git a/.github/latest_release_body.md b/.github/latest_release_body.md
@@ -6,10 +6,13 @@
 - See the [Changelog](https://ddnexus.github.io/pagy/changelog) for possible breaking changes
 <!-- whats_new_end -->
 
-### Changes in 9.1.1
+### Changes in 9.2.0
 
 <!-- changes_start -->
-- Simplify calendar code
+- Simplify the keyset API:
+  - Deprecate the :after_latest variable in favour of :filter_newest
+  - Add the keyset argument to the :filter_newest lambda
+  - Rename protected after_latest_query > filter_newest_query
 <!-- changes_end -->
 
 [CHANGELOG](https://ddnexus.github.io/pagy/changelog)
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,9 +20,16 @@ If you upgrade from version `< 9.0.0` see the following:
 
 ## Deprecations
 
-- None
+- `:after_latest` keyset variable: use `:filter_newest`
 <hr>
 
+## Version 9.2.0
+
+- Simplify the keyset API:
+  - Deprecate the :after_latest variable in favour of :filter_newest
+  - Add the keyset argument to the :filter_newest lambda
+  - Rename protected after_latest_query > filter_newest_query
+
 ## Version 9.1.1
 
 - Simplify calendar code

diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,7 +1,7 @@
 PATH
   remote: gem
   specs:
-    pagy (9.1.1)
+    pagy (9.2.0)
 
 GEM
   remote: https://rubygems.org/

diff --git a/README.md b/README.md
diff --git a/docs/api/keyset.md b/docs/api/keyset.md
@@ -34,16 +34,16 @@ less convenient for UIs.
 
 ### Glossary
 
-| Term                | Description                                                                                                                                                                                                                                                                              |
-|---------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| Term                | Description                                                                                                                                                                                                                                                              |
+|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `offset pagination` | Technique to fetch each page by changing the `offset` from the collection start.<br/>It requires two queries per page (or one if [countless](/docs/api/countless.md)): it's slow toward the end of big tables.<br/>It can be used for a rich frontend: it's the regular pagy pagination. |
-| `keyset pagination` | Technique to fetch the next page starting from the `latest` fetched record in an `uniquely ordered` collection.<br/>It requires only one query per page: it's very fast regardless the table size and position (if properly indexed). It has a very limited usage in frontend.           |
-| `uniquely ordered`  | When the concatenation of the values of the ordered columns is unique for each record. It is similar to a composite primary `key` for the ordered table, but dynamically based on the `keyset` columns.                                                                                  |
-| `set`               | The `uniquely ordered` `ActiveRecord::Relation` or `Sequel::Dataset` collection to paginate.                                                                                                                                                                                             |
-| `keyset`            | The hash of column/direction pairs. Pagy extracts it from the order of the `set`.                                                                                                                                                                                                        |
-| `latest`            | The hash of `keyset` attributes of the `latest` fetched record (from the latest page). Pagy decodes it from the `:page` variable and uses it to filter out the records already fetched.                                                                                                  |
-| `next`              | The next `page`, i.e. the encoded reference to the last record of the **current page**.                                                                                                                                                                                                  |
-| `page`              | The current `page`, i.e. the encoded reference to the `latest` record of the **latest page**.                                                                                                                                                                                            |
+| `keyset pagination` | Technique to fetch the next page starting from the `latest` fetched record in an `uniquely ordered` collection.<br/>It requires only one query per page: it's very fast regardless the table size and position (if properly indexed). It has a very limited usage in frontend. |
+| `uniquely ordered`  | When the concatenation of the values of the ordered columns is unique for each record. It is similar to a composite primary `key` for the ordered table, but dynamically based on the `keyset` columns.                                                                  |
+| `set`               | The `uniquely ordered` `ActiveRecord::Relation` or `Sequel::Dataset` collection to paginate.                                                                                                                                                                             |
+| `keyset`            | The hash of column/direction pairs. Pagy extracts it from the order of the `set`.                                                                                                                                                                                        |
+| `latest`            | The hash of `keyset` attributes of the `latest` fetched record (from the latest page). Pagy decodes it from the `:page` variable and uses it to filter the newest records.                                                                                               |
+| `next`              | The next `page`, i.e. the encoded reference to the last record of the **current page**.                                                                                                                                                                                  |
+| `page`              | The current `page`, i.e. the encoded reference to the `latest` record of the **latest page**.                                                                                                                                                                            |
 
 ### Keyset or Offset pagination?
 
@@ -116,8 +116,8 @@ If you need a specific order:
 - 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 
   `next` URL.
-- At each request, the `:page` is decoded and used to prepare a `when` clause that filters out the records already fetched, and 
-  the `:limit` of requested records is pulled.
+- 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.
 - You know that you reached the end of the collection when `pagy.next.nil?`.
 
 ## ORMs
@@ -166,19 +166,19 @@ Boolean variable that enables the tuple comparison e.g. `(brand, id) > (:brand,
 order, hence it's ignored for mixed order. Check how your DB supports it (your `keyset` should include only `NOT NULL` columns). 
 Default `nil`.
 
-==- `:after_latest`
+==- `:filter_newest`
 
 **Use this for DB-specific extra optimizations, if you know what you are doing.** 
 
-If the `:after_latest` variable is set to a lambda, pagy will call it with the `set` and `latest` arguments instead of 
-using its auto-generated query to filter out the records after the `latest`. It must return the filtered set. For example:
+If the `:filter_newest` variable is set to a lambda, pagy will call it with the `set`, `latest` and `keyset` arguments instead of 
+using its auto-generated query to filter the newest records (after the `latest`). It must return the filtered set. For example:
 
 ```ruby
-after_latest = lambda do |set, latest|
-  set.where(my_optimized_query, **latest)
+filter_newest = lambda do |set, latest, keyset|
+  set.where(my_optimized_query(keyset), **latest)
 end
 
-Pagy::Keyset(set, after_latest:)
+Pagy::Keyset(set, filter_newest:)
 ```
 
 ==- `:typecast_latest`
@@ -243,7 +243,7 @@ They may have been stored as strings formatted differently than the default form
   or similar tool to confirm.
 - Consider using the same direction order, enabling the `:tuple_comparison`, and changing type of index (different DBs may behave 
   differently)
-- Consider using your custom optimized `when` query with the [:after_latest](#after-latest) variable
+- Consider using your custom optimized `when` query with the [:filter_newest](#filter-newest) variable
 !!!
 
 ===
diff --git a/gem/apps/calendar.ru b/gem/apps/calendar.ru
@@ -15,7 +15,7 @@
 # DOC
 #    https://ddnexus.github.io/pagy/playground/#5-calendar-app
 
-VERSION = '9.1.1'
+VERSION = '9.2.0'
 
 # Gemfile
 require 'bundler/inline'

diff --git a/gem/apps/demo.ru b/gem/apps/demo.ru
@@ -18,7 +18,7 @@
 # DOC
 #    https://ddnexus.github.io/pagy/playground/#3-demo-app
 
-VERSION = '9.1.1'
+VERSION = '9.2.0'
 
 require 'bundler/inline'
 require 'bundler'

diff --git a/gem/apps/rails.ru b/gem/apps/rails.ru
@@ -15,7 +15,7 @@
 # DOC
 #    https://ddnexus.github.io/pagy/playground/#2-rails-app
 
-VERSION = '9.1.1'
+VERSION = '9.2.0'
 
 # Gemfile
 require 'bundler/inline'

diff --git a/gem/apps/repro.ru b/gem/apps/repro.ru
@@ -15,7 +15,7 @@
 # DOC
 #    https://ddnexus.github.io/pagy/playground/#1-repro-app
 
-VERSION = '9.1.1'
+VERSION = '9.2.0'
 
 require 'bundler/inline'
 require 'bundler'

diff --git a/gem/bin/pagy b/gem/bin/pagy
@@ -1,7 +1,7 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-VERSION = '9.1.1'
+VERSION = '9.2.0'
 APPS    = %w[repro rails demo calendar keyset_ar keyset_s].freeze
 LINUX   = RbConfig::CONFIG['host_os'].include?('linux')
 HOST    = '0.0.0.0'

diff --git a/gem/config/pagy.rb b/gem/config/pagy.rb
@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Pagy initializer file (9.1.1)
+# Pagy initializer file (9.2.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
 

diff --git a/gem/javascripts/pagy.min.js b/gem/javascripts/pagy.min.js