wor-paginate 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2382535974a5955b672ae5a22548b2100126afa69237fd5f76e7b5c18f6cd9e1
-  data.tar.gz: 977102640aba1c02a50d36181d2a4cc2fa3ab5e0bfe57b86587ae24fc4ada4ca
+  metadata.gz: decca93406ee541c53c128fb024c0be0ba58576b47a0c9cde5e834e33365c8e2
+  data.tar.gz: baae1708bf393145b589b872e3bf2a4ba44f3215efecc1a3bae34025cac0c9c4
 SHA512:
-  metadata.gz: acfa22f022acd7468c674cf723ca74b366deddf18d58320570951bd1067a36573a039468134ea4e1ee7586ea61e5fb685451e6fd1eb9f0a182d716a324177d2c
-  data.tar.gz: 2e1397984c3da7db0defdbe42e05f14e8692496d0411e9318e83f020ce3a3fe7e72ecfbfe7c748c3fd93263725d3752b89b8eda7e09fb3e729f3d6dacebf0cfb
+  metadata.gz: 75eb5ddfc44ed747a69fa797125776a4a2cdbe5e40ba9a3e7502a9af1685b844cad52d50c910d3856d591e8a31b7f6f1495a42542eabfb50a057992ba183d717
+  data.tar.gz: a140a0337bdb012c9821217f34cd2ea2099c0f8407cab21e8042c80ab5ee2c0ca8a375ad83d8931ed159f855cbc8ffc72458252c2c006694a9fa3e7da7d858a9

data/.gitignore

@@ -1,5 +1,7 @@
 spec/dummy/db/*.sqlite3
 spec/dummy/db/*.sqlite3-journal
+spec/dummy/db/*.sqlite3-shm
+spec/dummy/db/*.sqlite3-wal
 /test.sqlite3
 spec/dummy/log/*.log
 spec/dummy/tmp/

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## Change log
 
+### V0.5.0
+* [#6](https://github.com/icoluccio/wor-paginate/pull/6) Add block serialization to `render_paginated` - [@icoluccio](https://github.com/icoluccio).
+
+### V0.4.2
+* [#3](https://github.com/icoluccio/wor-paginate/pull/3) Add Pagy adapter - [@icoluccio](https://github.com/icoluccio).
+* [#4](https://github.com/icoluccio/wor-paginate/pull/4) Remove remaining rubocop:disable/:enable comments - [@icoluccio](https://github.com/icoluccio).
+* [#5](https://github.com/icoluccio/wor-paginate/pull/5) Document Kaminari/will_paginate Model.page collision - [@icoluccio](https://github.com/icoluccio).
+
 ### V0.4.1
 * [#2](https://github.com/icoluccio/wor-paginate/pull/2) Remove remaining dead Wolox links - [@icoluccio](https://github.com/icoluccio).
 

data/Gemfile

@@ -23,6 +23,7 @@ group :development, :test do
   gem 'generator_spec', '~> 0.10'
   gem 'kaminari', '~> 1.2'
   gem 'overcommit', '~> 0.71'
+  gem 'pagy', '~> 43.0'
   gem 'panko_serializer', '~> 0.8.5'
   gem 'puma', '~> 6.0'
   gem 'rake', '~> 13.0'

data/README.md

@@ -11,11 +11,14 @@ Wor::Paginate
     - [Basic usage](#basic-usage)
     - [Customizing output](#customizing-output)
       - [Custom serializers](#custom-serializers)
+      - [Block serialization](#block-serialization)
       - [Custom options](#custom-options)
       - [Custom formatters](#custom-formatters)
       - [Custom adapters](#custom-adapters)
-    - [Working with Kaminari or will_paginate](#working-with-kaminari-or-will_paginate)
+    - [Working with Kaminari, will_paginate, or Pagy](#working-with-kaminari-will_paginate-or-pagy)
+      - [Kaminari and will_paginate both define `Model.page`](#kaminari-and-will_paginate-both-define-modelpage)
     - [Test helpers](#test-helpers)
+      - [Field value chains](#field-value-chains)
   - [Contributing](#contributing)
   - [Releases](#releases)
   - [About](#about)
@@ -108,6 +111,19 @@ render_paginated DummyModel, each_serializer: CustomDummyModelSerializer
 ```
 where the serializer is just an [`ActiveModel::Serializer`](https://github.com/rails-api/active_model_serializers).
 
+#### Block serialization
+When you need a custom per-record payload that doesn't fit a serializer class, pass a block to `render_paginated`. The block receives each record and its return value is used as the serialized entry:
+
+```ruby
+def index
+  render_paginated(DummyModel) { |record| { id: record.id, label: record.name.upcase } }
+end
+```
+
+All pagination metadata (`count`, `total_pages`, `next_page_url`, etc.) is still computed and returned normally. The block only controls the content of the `page` array.
+
+The block form works with any adapter and takes precedence over `each_serializer` when both are supplied.
+
 #### Custom options
 ##### max_limit
 The max amount of items is passed through the `max_limit` option. You can set the value in the initializer or in the `render_paginated` method (If none is supplied, take the default value configured in the initializer). Default is 50.
@@ -263,11 +279,42 @@ There are also helper methods available to dynamically operate the gem's adapter
 When the gem paginates, it tries to adapt the content to the first adapter that is "adaptable" for the content (unless a custom adapter has been passed to render_paginated or a default_adapter has been defined in the initializer). So beware of which adapters (and in which order) you are leaving in the `Wor::Paginate::Config.adapters` array, because depending on those, the gem will try to adapt the content.
 
 
-### Working with Kaminari or will_paginate
-If either Kaminari or will_paginate is required in the project, Wor::Paginate will use them for pagination with no code or configuration change.
+### Working with Kaminari, will_paginate, or Pagy
+If Kaminari, will_paginate, or [Pagy](https://github.com/ddnexus/pagy) is required in the project, Wor::Paginate will use it for pagination with no code or configuration change.
+
+If more than one is available, Wor::Paginate prefers will_paginate, then Kaminari, then Pagy (the order they're checked in `Config::DEFAULT_ADAPTERS`). To opt out of one, for example if Pagy happens to be in your bundle for unrelated reasons, call `Wor::Paginate::Config.remove_adapter(Wor::Paginate::Adapters::Pagy)` in the initializer.
+
+#### Kaminari and will_paginate both define `Model.page`
+Kaminari and will_paginate each add their own `page` class method to your models, for the same purpose but with a different return value. Whichever gem's Rails initializer happens to run last silently overwrites the other's definition. This isn't affected by Gemfile order.
+
+Wor::Paginate's own adapter selection already routes around this (see the precedence above). If you specifically need Kaminari's own pagination behavior while will_paginate is also installed, rename Kaminari's method and subclass the built-in Kaminari adapter, overriding only the two methods that call `.page` literally:
+
+```ruby
+# config/initializers/kaminari.rb
+Kaminari.configure do |config|
+  config.page_method_name = :kpage
+end
+```
+
+```ruby
+# app/adapters/kaminari_renamed_adapter.rb
+class KaminariRenamedAdapter < Wor::Paginate::Adapters::Kaminari
+  def required_methods
+    %i[kpage]
+  end
+
+  def paginated_content
+    @paginated_content ||= @content.kpage(@page).per(@limit)
+  end
+end
+```
+
+```ruby
+render_paginated SomeModel, adapter: KaminariRenamedAdapter
+```
 
 ### Test helpers
-You can use the `be_paginated` matcher to test your endpoints. It also accepts the `with` chain method to receive a formatter.
+You can use the `be_paginated` matcher to test your endpoints.
 
 You only need to add this in your rails_helper.rb
 
@@ -300,6 +347,22 @@ describe YourController do
 end
 ```
 
+#### Field value chains
+
+You can assert specific pagination field values by chaining matchers:
+
+```ruby
+expect(response_body).to be_paginated
+  .with_total_count(42)
+  .with_current_page(1)
+  .with_next_page(2)
+  .with_previous_page(nil)
+  .with_total_pages(3)
+  .with_count(25)
+```
+
+Each chain is optional and independent. When a chain assertion fails, the error message names the specific field and the expected vs actual value.
+
 ### Working with panko-serializer
 
 The default formatter is [Active Model Serializer](https://github.com/rails-api/active_model_serializers).
@@ -327,7 +390,7 @@ and next, pass the specific serializer that you can use in the specific endpoint
 5. Commit your changes (`git commit -am 'Add some feature'`)
 6. Run RuboCop lint (`bundle exec rubocop lib spec --format simple`)
 7. Run rspec tests (`BUNDLE_GEMFILE=gemfiles/rails_8.1.gemfile bundle exec rspec`)
-8. Push your branch (`git push origin my-new-feature`) — the pre-push hook re-verifies both automatically
+8. Push your branch (`git push origin my-new-feature`) - the pre-push hook re-verifies both automatically
 9. Create a new Pull Request to `main` branch
 
 ## Releases

data/lib/generators/templates/wor_paginate.rb

@@ -20,6 +20,7 @@ Wor::Paginate.configure do |config|
   # Wor::Paginate::Adapters::WillPaginateAlreadyPaginated
   # Wor::Paginate::Adapters::WillPaginate
   # Wor::Paginate::Adapters::Kaminari
+  # Wor::Paginate::Adapters::Pagy
   # Wor::Paginate::Adapters::ActiveRecord
   # Wor::Paginate::Adapters::Enumerable
 
@@ -30,6 +31,7 @@ Wor::Paginate.configure do |config|
   # Adapters::WillPaginateAlreadyPaginated,
   # Adapters::WillPaginate,
   # Adapters::Kaminari,
+  # Adapters::Pagy,
   # Adapters::ActiveRecord,
   # Adapters::Enumerable
   # ]

data/lib/wor/paginate/adapters/pagy.rb

@@ -0,0 +1,46 @@
+require_relative 'helpers/total_count'
+
+# Used when render_paginated is called with an ActiveRecord directly, with the
+# pagy gem loaded. Something like
+### render_paginated DummyModel
+module Wor
+  module Paginate
+    module Adapters
+      class Pagy < Base
+        include Helpers::TotalCount
+
+        def adapt?
+          defined?(::Pagy::Offset) && super
+        end
+
+        def required_methods
+          %i[offset limit table_name]
+        end
+
+        def paginated_content
+          @paginated_content ||= pagy.records(@content)
+        end
+
+        delegate :count, to: :paginated_content
+
+        def total_pages
+          pagy.pages
+        end
+
+        def next_page
+          pagy.next
+        end
+
+        def previous_page
+          pagy.previous
+        end
+
+        private
+
+        def pagy
+          @pagy ||= ::Pagy::Offset.new(count: total_count, page: @page, limit: @limit)
+        end
+      end
+    end
+  end
+end

data/lib/wor/paginate/config.rb

@@ -16,6 +16,7 @@ module Wor
         will_paginate_paginated: Adapters::WillPaginateAlreadyPaginated,
         will_paginate: Adapters::WillPaginate,
         kaminari: Adapters::Kaminari,
+        pagy: Adapters::Pagy,
         active_record: Adapters::ActiveRecord,
         enumerable: Adapters::Enumerable
       }.freeze

data/lib/wor/paginate/formatters/base.rb

@@ -5,16 +5,17 @@ module Wor
     module Formatters
       class Base
         include Utils::UriHelper
-        attr_accessor :adapter, :content, :formatter, :options
+        attr_accessor :adapter, :formatter, :options
 
-        def initialize(adapter, options = {})
+        def initialize(adapter, options = {}, &block)
           @adapter = adapter
           @options = options
+          @serializer_block = block
         end
 
         def format # rubocop: disable Metrics/MethodLength
           {
-            page: serialized_content,
+            page: serialized_page,
             count: count,
             total_pages: total_pages,
             total_count: options[:total_count] || total_count,
@@ -35,9 +36,13 @@ module Wor
         end
 
         def paginated_content
-          # rubocop:disable Naming/MemoizedInstanceVariableName -- @content matches the public `content` attr_accessor above; renaming it would silently change what `content` returns.
-          @content ||= adapter.paginated_content
-          # rubocop:enable Naming/MemoizedInstanceVariableName
+          @paginated_content ||= adapter.paginated_content
+        end
+
+        def serialized_page
+          return paginated_content.map(&@serializer_block) if @serializer_block
+
+          serialized_content
         end
 
         def serialized_content

data/lib/wor/paginate/paginate.rb

@@ -2,13 +2,13 @@ require_relative 'utils/preserve_records_helper'
 
 module Wor
   module Paginate
-    def render_paginated(content, options = {})
-      return render_paginate_with_include(content, options) if includes?(options)
+    def render_paginated(content, options = {}, &block)
+      return render_paginate_with_include(content, options, &block) if includes?(options)
 
-      render json: paginate(content, options)
+      render json: paginate(content, options, &block)
     end
 
-    def paginate(content, options = {})
+    def paginate(content, options = {}, &block)
       current_url = request.original_url
       if (preserve_records = options[:preserve_records])
         content, current_url = Wor::Paginate::Utils::PreserveRecordsHelper
@@ -18,11 +18,12 @@ module Wor
       adapter = find_adapter_for_content(content, options)
       raise Exceptions::NoPaginationAdapter if adapter.blank?
 
-      formatter_class(options).new(adapter, options.merge(_current_url: current_url)).format
+      merged = options.merge(_current_url: current_url)
+      formatter_class(options).new(adapter, merged, &block).format
     end
 
-    def render_paginate_with_include(content, options)
-      render json: paginate(content, options), include: options[:include]
+    def render_paginate_with_include(content, options, &block)
+      render json: paginate(content, options, &block), include: options[:include]
     end
 
     def formatter_class(options)

data/lib/wor/paginate/rspec.rb

@@ -1,3 +1,5 @@
+CHAINABLE_FIELDS = %w[total_count count total_pages current_page next_page previous_page].freeze
+
 class MockedAdapter < Wor::Paginate::Adapters::Base
   def initialize
     super(nil, 1, 1)
@@ -28,28 +30,63 @@ class MockedAdapter < Wor::Paginate::Adapters::Base
   end
 end
 
+class PaginatedAssertion
+  attr_reader :failures, :formatted_keys
+
+  def initialize(response, formatter, expectations)
+    @response = response
+    formatted = formatter.new(MockedAdapter.new, _current_url: 'http://example.com/')
+    @formatted_keys = formatted.format.as_json.keys
+    @failures = key_failures + field_failures(expectations)
+  end
+
+  def pass?
+    @failures.empty?
+  end
+
+  private
+
+  def key_failures
+    return [] if @response.keys == @formatted_keys
+
+    ["expected keys #{@formatted_keys} but got #{@response.keys}"]
+  end
+
+  def field_failures(expectations)
+    CHAINABLE_FIELDS.filter_map do |field|
+      expected = expectations[field]
+      next if expected.nil?
+
+      actual = @response[field]
+      next if actual == expected
+
+      "expected #{field} to be #{expected.inspect} but got #{actual.inspect}"
+    end
+  end
+end
+
 RSpec::Matchers.define :be_paginated do
   match do |actual_response|
-    response = parse_response(actual_response)
     formatter = @custom_formatter || Wor::Paginate::Formatters::Base
-    @formatted_keys = formatter.new(MockedAdapter.new, _current_url: 'http://exaple.com/').format.as_json.keys
-    response.keys == @formatted_keys
+    expectations = CHAINABLE_FIELDS.index_with { |f| instance_variable_get(:"@expected_#{f}") }
+    @assertion = PaginatedAssertion.new(parse_response(actual_response), formatter, expectations)
+    @assertion.pass?
   end
 
   def parse_response(response)
     response.is_a?(Hash) ? response : JSON.parse(response.body)
   end
 
-  chain :with do |custom_formatter|
-    @custom_formatter = custom_formatter
-  end
+  chain(:with) { |formatter| @custom_formatter = formatter }
 
-  failure_message do |actual_response|
-    "expected that #{parse_response(actual_response)} to be paginated with keys #{@formatted_keys}"
+  CHAINABLE_FIELDS.each do |field|
+    chain(:"with_#{field}") { |value| instance_variable_set(:"@expected_#{field}", value) }
   end
 
+  failure_message { |_| @assertion.failures.join("\n") }
+
   failure_message_when_negated do |actual_response|
     "expected that #{parse_response(actual_response)} not " \
-     "to be paginated with keys #{@formatted_keys}"
+     "to be paginated with keys #{@assertion.formatted_keys}"
   end
 end

data/lib/wor/paginate/version.rb

@@ -1,5 +1,5 @@
 module Wor
   module Paginate
-    VERSION = '0.4.1'.freeze
+    VERSION = '0.5.0'.freeze
   end
 end

data/lib/wor/paginate.rb

@@ -3,6 +3,7 @@ require_relative 'paginate/adapters/active_record'
 require_relative 'paginate/adapters/enumerable'
 require_relative 'paginate/adapters/kaminari'
 require_relative 'paginate/adapters/will_paginate'
+require_relative 'paginate/adapters/pagy'
 require_relative 'paginate/adapters/kaminari_already_paginated'
 require_relative 'paginate/adapters/will_paginate_already_paginated'
 require_relative 'paginate/exceptions/dependency_error'

data/wor-paginate.gemspec

@@ -12,7 +12,7 @@ Gem::Specification.new do |s|
   s.email       = ["ignacio.coluccio@gmail.com", "martin.mallea@wolox.com.ar", "ramiro.rojo@wolox.com.ar", "lucas.voboril@wolox.com.ar"]
   s.homepage    = "https://github.com/icoluccio/wor-paginate"
   s.summary     = "Simplified pagination for Rails API controllers"
-  s.description = "Wor::Paginate is a gem for Rails that simplifies pagination, particularly for controller methods, while standardizing JSON output for APIs. It's meant to work both as a standalone pagination gem and as an extra layer over Kaminari and will_paginate"
+  s.description = "Wor::Paginate is a gem for Rails that simplifies pagination, particularly for controller methods, while standardizing JSON output for APIs. It's meant to work both as a standalone pagination gem and as an extra layer over Kaminari, will_paginate, or Pagy"
   s.license     = "MIT"
 
   s.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec)/}) }

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wor-paginate
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - icoluccio
@@ -10,7 +10,7 @@ authors:
 - lucasVoboril
 bindir: bin
 cert_chain: []
-date: 2026-08-01 00:00:00.000000000 Z
+date: 2026-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -54,8 +54,8 @@ dependencies:
         version: '9'
 description: Wor::Paginate is a gem for Rails that simplifies pagination, particularly
   for controller methods, while standardizing JSON output for APIs. It's meant to
-  work both as a standalone pagination gem and as an extra layer over Kaminari and
-  will_paginate
+  work both as a standalone pagination gem and as an extra layer over Kaminari, will_paginate,
+  or Pagy
 email:
 - ignacio.coluccio@gmail.com
 - martin.mallea@wolox.com.ar
@@ -84,6 +84,7 @@ files:
 - lib/wor/paginate/adapters/helpers/total_count.rb
 - lib/wor/paginate/adapters/kaminari.rb
 - lib/wor/paginate/adapters/kaminari_already_paginated.rb
+- lib/wor/paginate/adapters/pagy.rb
 - lib/wor/paginate/adapters/will_paginate.rb
 - lib/wor/paginate/adapters/will_paginate_already_paginated.rb
 - lib/wor/paginate/config.rb
@@ -120,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Simplified pagination for Rails API controllers
 test_files: []