wor-paginate 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd8ccaf4d5f8af78619449bf39383c133e41d193e3db20db6bb98f79077b6bdc
-  data.tar.gz: d42ed079f99f0ed72379507f0f9bfa4225e977074d9eea85dace43ef7120dce0
+  metadata.gz: decca93406ee541c53c128fb024c0be0ba58576b47a0c9cde5e834e33365c8e2
+  data.tar.gz: baae1708bf393145b589b872e3bf2a4ba44f3215efecc1a3bae34025cac0c9c4
 SHA512:
-  metadata.gz: f6bd84a58f0c0879756e2954c0e25ee7e0cdf3206c471b4640304f2cd9853e60029857d21000618a95d6678aa60b2c14a24fac4c6991f9d9df95419c4651a7d7
-  data.tar.gz: 3066ece4481767bf0adcdbe2c295c453b7ad2c8340d0175a20b27680886c79e01ede4c102b59aed0f806405275509e3108545c79448cd670e4b791af7b0ad8b4
+  metadata.gz: 75eb5ddfc44ed747a69fa797125776a4a2cdbe5e40ba9a3e7502a9af1685b844cad52d50c910d3856d591e8a31b7f6f1495a42542eabfb50a057992ba183d717
+  data.tar.gz: a140a0337bdb012c9821217f34cd2ea2099c0f8407cab21e8042c80ab5ee2c0ca8a375ad83d8931ed159f855cbc8ffc72458252c2c006694a9fa3e7da7d858a9

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 ## 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).

data/README.md

@@ -11,12 +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, 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)
@@ -109,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.
@@ -299,7 +314,7 @@ 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
 
@@ -332,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).
@@ -359,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/wor/paginate/formatters/base.rb

@@ -7,14 +7,15 @@ module Wor
         include Utils::UriHelper
         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,
@@ -38,6 +39,12 @@ module Wor
           @paginated_content ||= adapter.paginated_content
         end
 
+        def serialized_page
+          return paginated_content.map(&@serializer_block) if @serializer_block
+
+          serialized_content
+        end
+
         def serialized_content
           paginated_content.as_json
         end

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.2'.freeze
+    VERSION = '0.5.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: wor-paginate
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - icoluccio
@@ -10,7 +10,7 @@ authors:
 - lucasVoboril
 bindir: bin
 cert_chain: []
-date: 2026-08-04 00:00:00.000000000 Z
+date: 2026-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -121,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: []